Skip to main content
skill CX Codex

nemo-relay-debug-runtime-integration — Claude Code skill: install

The nemo-relay-debug-runtime-integration skill traces NeMo Relay runtime faults across loading, scopes, events, plugins, and adaptive wiring. Use it when the package is present but app behavior is wrong.

Apache-2.0 197 installs ★ 4,106 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NVIDIA/skills --skill nemo-relay-debug-runtime-integration -a claude-code
Open on GitHub

What nemo-relay-debug-runtime-integration does

The skill starts by locating the failing runtime layer. It checks whether a binding or native artifact loads, whether a scope is active at the failing call, and whether execution follows the expected scope stack. It also checks subscriber, exporter, and plugin activation, event registration, and the selected API path: managed execute, manual lifecycle, typed wrappers, or adaptive/plugins.

Its troubleshooting matrix covers Python, Node.js, Go, and Rust failures, empty scope stacks, request leakage, missing subscriber events, incomplete event fields, mixed ATIF output, provider payload conversion, and plugin validation. It also separates OpenTelemetry and OpenInference checks for Relay 0.6 and 0.7. A call outside an active scope will not produce the expected lifecycle events.

Python checks use uv sync and an import test from the application environment. Go diagnosis needs the release FFI library and loader paths, with DYLD_LIBRARY_PATH on macOS. A Node.js native addon must be reinstalled and rebuilt from its binding package.

What it helps with

  • trace a native binding or library load failure
  • verify scope ownership across tasks and workers
  • restore missing lifecycle events and fields
  • check plugin and adaptive component wiring
  • diagnose OpenTelemetry or OpenInference export

Example prompts for the agent

  • Find why this NeMo Relay call runs without an active scope, then inspect task boundaries.
  • Trace why the subscriber receives no events after registration.
  • Check the adaptive component path and config when runtime behavior stays unchanged.

How to install nemo-relay-debug-runtime-integration

1Skills CLI (Vercel)

npx skills add NVIDIA/skills --skill nemo-relay-debug-runtime-integration -a claude-code

2Manually: put the files in place

~/.claude/skills/nemo-relay-debug-runtime-integration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nemo-relay-debug-runtime-integration/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about nemo-relay-debug-runtime-integration

How do I install nemo-relay-debug-runtime-integration in Claude Code?

Run npx skills add NVIDIA/skills --skill nemo-relay-debug-runtime-integration -a claude-code, then check ~/.claude/skills/nemo-relay-debug-runtime-integration/SKILL.md.

What does nemo-relay-debug-runtime-integration do?

It diagnoses NeMo Relay runtime integration faults, including binding loads, scope activity, event registration, plugin setup, and telemetry export.

How does export troubleshooting differ between Relay 0.6 and 0.7?

For 0.6, check the separate exporter, http_binary or grpc, endpoint, headers, target support, and an active Tokio runtime for native gRPC. For 0.7, check the typed projection, endpoint, headers, TLS, and target support; the subscriber owns the native gRPC runtime.

Source text

SKILL.md · Apache-2.0
---
name: nemo-relay-debug-runtime-integration
description: Use this skill when NeMo Relay is installed or imported but application-side runtime behavior is missing or incorrect, including load failures, inactive scopes, missing events, and plugin or adaptive wiring problems.
license: Apache-2.0
metadata:
  author: NVIDIA Corporation and Affiliates
---

# Debug Runtime Integration

Use this skill when NeMo Relay is present in the application but something is not
working.
Start by proving which runtime layer is failing before changing configuration.

## First Checks

- Can the binding or native artifact load?
- Is there an active scope when the failing call runs?
- Is the work happening on the expected scope stack?
- Is the subscriber/exporter/plugin configuration actually active?
- Did the app choose the right public API layer: managed execute vs manual
  lifecycle vs typed wrappers vs adaptive/plugins?

## Common Failure Classes

- Python native extension missing
- Go dynamic library not on the loader path
- Node native addon not built or not loading
- Execute call outside a scope
- Missing events because registration never happened
- Concurrency causing the wrong scope stack to be active
- Adaptive component never initialized or config validation ignored

## Embedded Troubleshooting Matrix

- **Rust build failure**: run the narrowest core build first, then expand to the
  affected binding or workspace command.
- **Python import failure**: rebuild the virtual environment and native
  extension with `uv sync`, then run a small Python test or import check from
  the same environment as the application.
- **Node.js addon failure**: reinstall and rebuild the native addon from the
  Node binding package before debugging application code.
- **Go loader failure**: build the release FFI shared library and point both the
  linker and runtime loader at the release output directory; use the macOS
  dynamic-library path variable (`DYLD_LIBRARY_PATH`) on macOS.
- **Scope stack empty**: the work is outside an active scope or crossed a thread,
  task, goroutine, or worker boundary without the intended stack.
- **Work leaks across requests**: separate requests are sharing one scope stack;
  create a fresh stack per independent request or agent.
- **Middleware missing or ordered incorrectly**: check global vs scope-local
  registration, active scope ancestry, names, and priority values.
- **Subscriber missing events**: register before the events are emitted; for
  scope-local subscribers, ensure the current scope is the owner or descendant.
- **Event fields missing**: managed helpers populate semantic fields; manual
  lifecycle calls require explicit params for input, output, model names, and
  tool call IDs.
- **ATIF empty or mixed**: register before work starts, use one exporter per run
  or clear between runs, and separate concurrent agents by root scope.
- **Provider payload conversion failure**: convert non-JSON provider objects,
  SDK handles, callbacks, streams, or class instances with explicit codecs.
- **Plugin validation failure**: validate config independently from runtime
  registration and check required fields, value types, defaults, and config
  source.
- **Adaptive behavior unchanged**: confirm instrumentation emits events, the
  adaptive component is enabled, policy allows the behavior, and the call path
  reaches the configured component.
- **OpenTelemetry or OpenInference export failure**: first identify the Relay
  version. For 0.6, check the separate exporter, `http_binary` versus `grpc`,
  endpoint, headers, target support, and an active Tokio runtime for native
  gRPC. For 0.7, check the typed projection, endpoint, headers, TLS, and target
  support; the subscriber owns the native gRPC runtime.
- **Callback succeeded but no lifecycle events appear**: confirm the integration
  uses managed execute helpers or balanced manual start/end APIs, not only the
  underlying business callback.

## Related Skills

- `nemo-relay-get-started`
- `nemo-relay-instrument-context-isolation`
- `nemo-relay-plugin-adaptive-tuning`
- `nemo-relay-plugin-build`

© NVIDIA Corporation and Affiliates · Apache-2.0 · NVIDIA/skills

Similar skills

All skills for AI and ML →

From the same set312

The whole set →
nemo-relay-install The nemo-relay-install skill identifies your installation target and deploys the current stable NeMo Relay package, resolving prerequisites and verifying availability. Works across agent runtimes, frameworks, and language bindings. CX Codex +1 227installs nemo-relay-instrument-calls nemo-relay-instrument-calls wraps tool and LLM provider call sites with NeMo Relay execution scopes. Keeps business logic intact while attaching lifecycle events, intercepts, and guardrails. CX Codex +1 224installs nemo-relay-instrument-context-isolation The nemo-relay-instrument-context-isolation skill keeps NeMo Relay scope stacks separate across concurrent work and preserves event ancestry as tasks cross execution boundaries. CX Codex +1 211installs nemotron-asr-finetune nemotron-asr-finetune coordinates domain and language adaptation for NVIDIA Nemotron Speech and Riva ASR, picking the lowest-cost path from word boosting to full fine-tuning. CX Codex +1 210installs nemo-relay-instrument-typed-wrappers nemo-relay-instrument-typed-wrappers configures NeMo Relay typed wrappers and provider codecs while keeping JSON middleware semantics intact. CX Codex +1 182installs nemo-relay-plugin-build nemo-relay-plugin-build is a skill for packaging reusable NeMo Relay behavior as config components or dynamic plugins, with validation and rollback for plugins shared across apps or teams. CX Codex +1 181installs nemo-relay-plugin-adaptive-tuning nemo-relay-plugin-adaptive-tuning is a Claude Code skill that configures and evaluates NeMo Relay adaptive behavior from runtime signals, including telemetry, parallelism, hints, and prompt-cache planning. CX Codex +1 178installs nemo-relay-migrate-from-flow nemo-relay-migrate-from-flow — a skill that automates code, documentation, and config migration from NeMo Flow to NeMo Relay. Handles Python, Rust, Node.js, Go, C FFI, CLI, and observability surfaces. CX Codex +1 171installs

Project sponsors

Companies that keep this analytics open