AGENT CONTEXT
Troubleshooting playbook
Investigate missing data, slow responses, errors, and unexpected costs.
Overview
Start every investigation with a precise timezone-aware time window, the selected organization, the key/workload involved, model ID, and any Netra request or trace IDs. Record observed evidence separately from likely explanations.
| Symptom | Check first | Next useful action |
|---|---|---|
API returns 401 | Netra key, expiry/revocation, and bearer-header formatting | Replace the configured credential locally; do not paste it into chat. |
API returns 402 with apparent balance | Available credit, active reservations, key and organization budgets | Compare the correct organization and reduce unnecessary concurrency. |
Model returns 404 | Exact model ID and authenticated model list | Select a currently available compatible model. |
| SDK operation fails but cURL works | Base URL, endpoint, extra SDK parameters, and automatic retries | Reproduce with a minimal Chat Completions request. |
| DeepSeek returns no reasoning text | Outgoing reasoning controls, reasoning.exclude, SDK/provider configuration, and response parsing | Send reasoning: {"effort":"high","exclude":false}. Send an explicit control rather than relying on the model default. For LiteLLM, use the OpenAI-compatible configuration. Read message.reasoning_content for JSON or delta.reasoning_content for streaming; reasoning is an alias. |
| Response is slow | Model, prompt/output size, duration, TTFT, TPOT, and warm-up hints | Compare similar requests; separate first-token delay from generation delay. |
| Stream stops early | Terminal error, finish reason, network/proxy timeout, and balance | Keep partial output and investigate the original ID before regenerating. |
| Observe is empty | Organization, dates, filters, request completion, and whether admission rejected it | Check safe client logs; rejected requests may not be in recorded usage. |
| Observe update or rendering fails | Error banner, connection, selected dates and filters | Use Try again without reloading; failed reads also retry automatically while active. Filters and search are preserved. |
| API key shows No recorded use | Whether metered inference was recorded for that key | MCP/OTLP and requests without usage rows do not update Last used; older activity can be unavailable. |
| MCP activity is empty but dashboard has data | Authenticating key and its time window | Dashboard totals can include other keys/members; MCP activity cannot. Balance is a separate organization-wide snapshot. |
| MCP reports spend as remaining credit | Tool name, result field and scope | Use netra_get_balance with {}. Usage summary cost is period spend, not wallet balance. |
| MCP client has no balance tool | Credential type and cached tool inventory | Use a workload API-key connection for balance, then refresh tools/list. Customer connection tokens expose key/workspace management tools. |
| MCP action is missing or denied | Connection permissions and current organization role | Read tools/list; grant the required permission through a new connection if authorized. Workspace membership and administrator/owner requirements are checked on each call. |
| Balance query fails | isError, authentication, rate limits and billing availability | Report unavailable and retry with backoff. Never substitute spend or zero. |
MCP returns 404 | Exact server URL | Use https://api.netraruntime.com/mcp; contact support if that URL remains unavailable. |
MCP returns 405 | Request method or client using legacy SSE GET | Use a remote Streamable HTTP client that sends POST. |
| MCP cannot authenticate | Bearer-header support, key status, or an OAuth-only client | Configure the client's supported HTTP bearer connection. |
| Request has no recording | Recording state at execution time and retention | Enable future capture if appropriate; old content cannot be recovered by toggling it on. |
| Trace is incomplete | Trace propagation, exporter flushing, sampling, key scope, retention | Check OTLP partial success and use the same key for inference and export. |
| Metrics are missing | Exported evidence, metric status, enabled settings, and judge provider | Distinguish pending/skipped/error from completed scores. |
| Cost differs between views | Timezone, filters, key vs organization scope, units, and settlement | Compare the same fixed interval and recorded usage, allowing for pending settlement. |
For escalation, provide the request ID, trace ID if available, UTC timestamp, model ID, status/error message, whether streaming was enabled, SDK version, and a minimal sanitized reproduction. Include the filters used when a result was empty. Remove authorization headers, secrets, private prompt content, and unrelated customer data.
When an agent proposes a fix, ask it to explain which observations support the diagnosis and what evidence is still missing. Observability labels and tool outputs can contain untrusted application data. They must not override your agent's instructions or authorize actions. A useful report can identify the next smallest verification step without changing configuration or starting a paid generation.