Troubleshooting

Start with configuration and service state:

./release/abada-platform doctor dev --no-pull
./release/abada-platform status dev
./release/abada-platform logs dev

Symptom	Check
Production config exits immediately	Replace every required placeholder in .env.prod; validate DNS, CORS and OIDC URLs
Server start stops at set ABADA_DOMAIN	Set ABADA_DOMAIN and ABADA_ACME_EMAIL in .env.server; the secrets are generated
Browser shows TRAEFIK DEFAULT CERT on the server profile	DNS for the domain and its wildcard does not reach the VM yet, port 80 is closed, or the records are proxied; see ./release/abada-platform logs server
Server sign-in returns “Invalid redirect uri”	ABADA_DOMAIN changed after the first start; rerun ./release/abada-platform up server
Port 80/443 already used	Stop the conflicting service or move Abada to a dedicated host
Studio shows configuration error	Inspect the generated /config.js; all four runtime values are mandatory and URLs must be HTTP(S)
Login loops	Match redirect URI, web origin, issuer, realm and client ID exactly
Engine unhealthy	Check PostgreSQL health and engine logs; telemetry must not be the cause
No Grafana data	Confirm the telemetry overlay is present, then inspect Collector, Alloy and Grafana containers
Workflow succeeds while collector is down	Expected: telemetry export is best-effort and independent of workflow correctness
Instance stays ACTIVE at an agent node	Expected without a worker or AI provider; check the Agent Worker is Online in Operations and a provider serving the node’s model is set in Studio → Settings → AI Providers
Worker shows Error or Offline in Operations	Inspect last rejection and consecutive failures; verify engine URL, OIDC client credentials and LLM endpoint reachability
Deployment refused with a model error	The node’s model (or one of its fallback_models) is outside ABADA_AGENT_ALLOWED_MODELS
Cost shows + unpriced	Neither your prices nor the public catalog knew the model at the time of the call (Settings → Model Prices shows each model’s source). Add a price; earlier calls stay unpriced
Test & save refuses a provider	The test call failed; the message gives the provider’s reason (invalid key, unknown model, quota). Nothing was saved; fix and save again
Evidence payloads answer 403	Reading payloads needs the abada-evidence-reader group, which abada-admin does not imply
Deployment refused with ABADA-APL-CALL-001	A call-process step calls a process this project has not deployed yet, or passes an input the called process does not declare in metadata.variables. Deploy the called process first, or fix the inputs
Deployment refused with ABADA-APL-TOOL-002	A tools entry names a tool server the project does not define, a tool its server does not list, or a policy looser than the server’s. Add or fix the TOOL_SERVER resource, or the reference
Agent task fails with “tools outside the configured allow-list”	The worker’s ABADA_AGENT_ALLOWED_TOOLS does not list the tool’s server
Deployment refused: “cycle back to node … needs a bound”	A route goes back to an earlier step that declares no loop. Add loop: { max_iterations: N } to that step (Studio: Add loop bound)
A reviewer cannot see a task	The task’s assignees must match one of their identity groups or a project task group (Admin → Projects), and they need abada-task-user
Instance stops with an open incident	List them with GET /api/v1/projects/{projectId}/incidents. WORK_FAILED: a step’s last attempt failed and it has no on_error; LOOP_EXHAUSTED: a loop hit max_iterations with no on_exhausted; MISSING_CORRELATION_KEY: a message wait has no correlationKey value. Fix the cause, then POST .../incidents/{incidentId}/retry or cancel the instance — see Operate running processes
An agent step waits with EXTERNAL_TASK_DEFERRED in its history	Every model of the step is rate-limited or unavailable; the engine retries with a growing delay without using up attempts. Add fallback_models, raise the provider quota, or retry a WORK_FAILED incident on another allowed model
A human task shows as escalated	It passed its sla_hours; the escalate_to groups can now claim it. It is still open and completes normally
No Insight proposals appear	Confirm ABADA_INSIGHT_ENABLED=true and that enough terminal facts exist (thresholds under abada.insight.*); proposals are never auto-approved

Render the merged configuration without starting anything:

docker compose --env-file .env.prod \
  -f compose.yaml -f compose.prod.yaml config

Do not post .env.prod, JWTs, authorization headers or full sensitive payloads in support reports. Include exact image versions, Compose version, health output, redacted logs and the command that failed.