DocsBook a demo

Platform

Platform overviewArchitectureWorkflow orchestrationGitOps configurationGovernance and AAAAI and MCPKnowledge and contextRuntime and executionEvidence and monitoring

Use cases

All use casesProduction incidentRelease preparationHotfix to productionSecurity scan triage
Why NopsAIIntegrationsSecurity

Resources

All resourcesAI agent governanceMCP governanceMCP securitySelf-hosted platforms
PricingGitHub

Company

How a run worksAboutContactBook a demo

Troubleshooting index

Symptom to likely cause, with the page that explains the fix.

TroubleshootingOperatorAdministratorAutomation author

Key points

  • The UI will not let anyone in — check GET /v1/setup/preflight; it names the blocker without a token.
  • `/healthz` never becomes ready — the API is retrying an unreachable database. /livez still answers.
  • A run stays queued — no reachable dispatch-enabled runner matches the run scope. Check the dispatcher fleet view.
  • A Git push starts nothing — compare event name, branch, and changed paths against the trigger rule, then check deliveries.
  • A goal fails immediately — test the Model; an unconfigured profile, a scope restriction, and an AAA denial produce different messages.
  • A pipeline is rejected on save — validation names the exact step, task, or directive. Read the message before editing the graph.
  • PDF output fails — no reachable Gotenberg at FINAL_OUTPUT_PDF_RENDERER_URL.
  • Runner logs show unavailable — the System Logs provider cannot reach the Docker host or an owned pod in the runner namespace.
  • A GitOps change was reverted — a UI or API edit created a database override; push the change back to the owning repository.
  • `ImagePullBackOff` on step pods — a missing or wrong imagePullSecret, not a NopsAI credential assignment.

How it works

Two error classes are easy to confuse. A validation error happens before anything is queued and always names a directive. A runtime failure happens during execution and appears in the run logs against a specific step or task.

When a value you expected to be masked appears in logs, check whether it was declared under secrets or marked sensitive: true — agent-side masking is driven by your declarations.

Examples

Triage in the order that narrows fastestbash
# 1. is the control plane healthy at all?
curl -s "$NOPSAI_URL/livez"; curl -s "$NOPSAI_URL/healthz"

# 2. is there anywhere to run work?
curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/system/dispatcher" | jq '.runners'

# 3. did the run start, and what did it say?
curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/runs/$RUN_ID" | jq '.status'
curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/runs/$RUN_ID/logs" | jq -r '.[].line' | tail -30

# 4. if the run never started, the answer is in the platform logs
curl -s -H "Authorization: Bearer $NOPSAI_TOKEN" "$NOPSAI_URL/v1/system/logs/sources" | jq
Result

Each step rules out a layer. A run that never started is never a pipeline problem.

Implementation evidence

  • doc/runtime-flows.md

    Where each stage of a run can fail.