---
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`