Troubleshoot NeMo Guardrails Gateway
Start with the failing phase: application startup, a request before response headers, a stream after headers, or shutdown. Record the operation, selected provider instance, dialect, HTTP status, and error code. For a stream, record whether an error event followed the headers and whether any text had already arrived. Use a minimal synthetic request when reproducing a failure; exclude credentials and private request or response content from shared diagnostics.
Startup Fails or the Embedded Runtime Is Unavailable
From the directory containing your manifest, run:
Use the command result to identify the failing startup phase:
inspect describes routes, profiles, and fixed Rails selections. It does not
execute checks or establish upstream compatibility. Compare its output with the
actual deployed manifest, then use the embedding recipe
if a parent application owns startup. Treat inspected deployment addresses as
operational metadata when sharing output.
A Request Is Rejected or a Check Fails
For the shipped OpenAI bindings, use the error code as well as the status:
The error mapping defines additional routing and size-limit codes. Unsupported content on a guarded route does not fall back to pass-through. Conversely, unselected operations can pass through without inspection: verify the route as well as the enabled Rails checks when a request unexpectedly avoids blocking.
Use the coverage table and contract exports to identify a field mismatch. Add a deliberate binding extension only when you have established how the new field should be handled.
Streaming Is Delayed or Ends With an Error
Reproduce with curl -N -i using the streaming request.
-N disables curl’s output buffering; -i shows when response headers arrive.
If your deployment permits direct access, compare the same synthetic request
through the ingress and directly to NeMo Guardrails Gateway to isolate ingress buffering.
Use the following observations to locate the failure:
Accepted upstream headers do not validate the event body; even the first event can fail after downstream headers are sent. Refer to streaming lifecycle for release and cleanup ordering.
A Client Disconnects or Shutdown Reports Incomplete Cleanup
Exercise disconnect behavior through the actual ingress using a stream long
enough to interrupt. Start the request with curl -N, interrupt it, and observe
the upstream connection and gateway cleanup diagnostics.
These warning messages identify different cleanup owners:
Each message ends with resources may remain open. Configure the host’s Python
logging handlers to retain these warnings. A timeout means cleanup was not
confirmed; a finished HTTP response does not prove release. Cleanup attempts
are shielded and cooperatively bounded, so blocking or cancellation-suppressing
code can defeat the intended budget. Custom owners must support repeatable,
cancellation-cooperative closing.
Check resource behavior after repeated disconnects and shutdown, including open
connections and tasks owned by your transport or checking services. Keep network
read/idle timeouts separate from cleanup budgets; changing the manifest’s
timeout is not a cleanup fix. Follow the transport ownership reference
and shutdown behavior
when investigating a resource leak.