# Troubleshooting Matrix

| Subsystem | Symptom | First checks | Next action |
|---|---|---|---|
| `serve` | `401/403` responses | API key, scopes, workspace header | validate RBAC roles and allowed workspaces |
| `state_store` | state not loading | schema version, backend path/DSN | run `storage upgrade-check` and inspect backend health |
| `cli` | operator command reads empty data unexpectedly | check whether the command used `--db-path` while production data lives behind `--dsn` or `LOGOS_ADK_*_DSN` | rerun with the correct backend input and avoid mixing SQLite path and PostgreSQL DSN for the same store |
| `learning` | evaluation/improvement commands show no runs in production | `LOGOS_ADK_LEARNING_BACKEND`, `LOGOS_ADK_LEARNING_DSN`, workspace filter | point the command at the PostgreSQL learning store with `--dsn` or env and verify the workspace actually has captured runs |
| `retrieval_learning` | retrieval summary or source scores are empty | `--dsn` / `LOGOS_ADK_RETRIEVAL_DSN`, workspace scope, config-driven table prefix | verify the retrieval DSN, then rerun with the same workspace and config used by production ingestion |
| `model_routing_learning` | routing leaderboard or canaries look missing | `--dsn` / `LOGOS_ADK_MODEL_ROUTING_DSN`, task type, confidence tier | confirm the routing store DSN and filters, then inspect whether production traffic actually recorded routing events |
| `tool_workflow_learning` | tool rankings or loop recommendations are empty | `--dsn` / `LOGOS_ADK_TOOL_WORKFLOW_DSN`, workspace/task filters | verify the workflow DSN and confirm the agent is emitting tool/workflow learning events |
| `reflection_memory` | reflection lessons disappear after restart | `--reflection-dsn` / `LOGOS_ADK_REFLECTION_DSN` vs local `--reflection-db-path` | standardize on one backend in production and stop writing lessons to ad hoc local SQLite files |
| `prompt_registry` | continuous eval or transfer flows cannot resolve prompt versions | `--prompt-registry-dsn` / `LOGOS_ADK_PROMPT_REGISTRY_DSN`, environment, workspace filters | verify the prompt registry backend and inspect whether the expected prompt was promoted in that environment |
| `continuous_eval` | jobs do not restore after restart | `--continuous-eval-dsn` / `LOGOS_ADK_CONTINUOUS_EVAL_DSN`, `--quality-dsn`, `--prompt-registry-dsn` | make all evaluation stores explicit, then rerun `evaluation restored-jobs` against the production DSNs |
| `quality_history` | regression jobs run but quality history looks empty | `--quality-dsn` / `LOGOS_ADK_QUALITY_DSN`, run status, DB credentials | verify the quality backend and check whether runs are being persisted into PostgreSQL instead of a leftover local file |
| `scaling` | duplicate work | missing idempotency key | enable idempotency on caller side |
| `scaling` | dead-letter growth | task errors and retry budget | replay after fixing the root cause |
| `observe` | missing metrics | exporter config and flush path | verify dashboards and alert rules |
| `security` | blocked request | input validation, prompt shield, PII policy | inspect audit logs with trace ID |
