Troubleshooting
Diagnose access errors, incomplete evaluations, missing traces, and slow loading.
Start with the result, not only the status code
A successful HTTP response can still describe a blocked, degraded, unavailable, or unconfigured evaluation. Inspect allowed, evaluation_status, errors, and policies_evaluated together.
| Symptom | Check | Next action |
|---|---|---|
not_configured | Enabled policies and agent scope | Create or enable the intended policy; repeat with the same agent name. |
allowed: true with findings | Policy Warning mode or wrapper monitoring | Confirm intended behavior before switching to blocking. |
| Denied with no normal finding | Failed blocking detector | Inspect errors; restore the missing detector dependency. |
401 / 403 | Key destination, validity, revocation, scope | Use an ingest key for evaluation; a test key is for CI. |
429 | Request limits and organization quota | Back off within a bounded retry budget or adjust the entitled capacity. |
| Missing trace | no_trace, instrumentor, exporter, capture mode | Verify actual backend receipt after flushing. |
| Generic span names or no prompt | Metadata-only capture | Expected when content retention is disabled; resubmit input for a retest. |
| SDK timeout | Cold detector/model load, network, database | Measure each layer; configure a timeout that matches the required failure behavior. |
Liveness and readiness
curl --fail-with-body "$NYRAXIS_BASE_URL/health"
curl --fail-with-body "$NYRAXIS_BASE_URL/ready"/health indicates that the API process responds. /ready checks deployment dependencies and can return 503 when broad detector readiness is unavailable, even if storage, background processing and Secrets Detection are usable. Inspect the returned checks; do not substitute liveness for readiness.
Model-backed detectors
Check installed dependencies, model files, approved download access, configured remote endpoints, and provider credentials. A limited check does not establish complete contextual coverage. A healthy provider status is also not an accuracy benchmark.
Use Secrets Detection for a deterministic synthetic first evaluation. Enable additional detectors one at a time, then measure them with representative safe and unsafe examples.
Slow dashboard or evaluation requests
Separate browser rendering, frontend authentication/proxy time, backend authorization and audit writes, database queries, model loading, and actual provider execution. Measure cold and warm requests and inspect a percentile distribution under bounded concurrency.
Place the application and database in appropriate nearby regions, reuse connection pools, verify TLS, and inspect PostgreSQL query plans before changing indexes. Never remove current membership checks, weaken TLS, or turn an evaluator failure into an allow to improve a timing result.
The workspace's local and injected-delay measurements are engineering evidence for those conditions, not a promise for your cloud database or network.
Scans remain queued
Confirm workload and dispatcher workers consume their configured queues, the scheduler is running, and lease/recovery tasks can reach the database and Redis. The target must be reachable from that worker network. Inspect the persisted job before retrying; an uncertain external call may already have reached the target.
Search or documentation problems
Use the docs search button or Ctrl/⌘ K. If search is unavailable, retry or use the sidebar. Code blocks and wide tables scroll within their own panels on a narrow screen. The plain-text documentation provides another navigation entry point.
Report a useful issue
Record the app/SDK version, operation, timestamp, trace/job ID, selected policy versions, status, and sanitized error code. Exclude API keys, cookies, request bodies, credentials, and real customer content. A synthetic reproducer is preferable.