Field guide
Troubleshooting by symptom
Symptom -> cause -> fix for the failures people actually hit with NovaOS. Use novaos_explain_error for any error text.
Setup and CLI
| Symptom | Cause | Fix |
|---|---|---|
command not found: novaos-cli (from an AI app) |
GUI apps have a minimal PATH | This server adds common paths; else reopen the terminal / check npm or Homebrew bin dir |
error: unknown option '--version' |
flag is -V |
novaos-cli version |
| CLI talks to localhost unexpectedly | env in config.json not defined -> silent fallback to local | novaos_env_list, novaos_env_setup |
Unknown environment "x" |
not in ~/.novaos/environments.json | novaos_env_setup {"env":"x"} |
[ORG_CONTEXT_REQUIRED] / 403 everywhere |
token has no org | novaos_org_use |
Authentication required / Session expired |
not signed in / refresh failed | novaos_auth_login |
NOVAOS_MARKETPLACE_URL is required for env |
env entry lacks marketplaceUrl | novaos_env_setup with marketplace_url |
platform binary is missing / musl error |
npm launcher download failed / Alpine | reinstall, Homebrew, glibc image |
| manifest validation fails on A2A | CLI < 2.2 | upgrade CLI |
could not resolve a publisher slug |
no developer profile | Developer > Publisher Profile, or --publisher |
Build and publish
| Symptom | Cause | Fix |
|---|---|---|
Docker is required / cannot connect to daemon |
Docker not running | start Docker Desktop |
Agent Card drift |
manifest skills != @agent.skill ids |
align (one skill run) |
Invalid agent_module / card capture failed |
points to FastAPI app or import error | server:agent (the AgentBuilder); novaos_agent_card |
base_image must match novaos/base-... |
Dockerfile image put in manifest | novaos/base-plain:1.0 |
placeholder publisher "local-publisher" |
offline init | real slug |
| existing version | version already published | bump manifest + AGENT_VERSION |
| Stuck at PENDING_REVIEW | needs platform-admin approval | /admin/approvals (novaos_ui_guide approvals) |
SA_AGENT_INSTALL_FAILED (Failed to store agent secrets) |
requiredSecrets broken on some envs | use installation_config.config_schema |
Runs
| Symptom | Cause | Fix |
|---|---|---|
TASK_STATE_REJECTED / skillId required |
multi-skill agent, no selector | one dispatcher skill |
| JSON-RPC -32009 | missing A2A-Version: 1.0 |
send header |
| Task FAILED though handler returned | lowercase status | COMPLETED/FAILED |
| Run cancelled ~30 s | no bytes on stream | heartbeat every 10 s |
fetch failed ~30 s |
no response headers in 30 s | stream immediately |
| Stream ended without a result | cut at ~300 s | poll + replay (novaos_run_wait); never re-run |
| 404 THREAD_NOT_FOUND | thread not gateway-created | retry without thread; store returned id |
503 Agent execution dispatch failed |
stale thread / dispatch | retry once on a fresh thread |
| 429 ConcurrencyLimitError | org SA run cap (~8) | back off, "Waiting for capacity" |
403 exceeded quota after start |
pod quota full | wait minutes; reduce concurrent runs |
INSTANCE_NOT_FOUND / not owned by principal |
instance of another user/SA or uninstalled | use the caller's own instance; reinstall |
user_token_missing |
run request without X-NovaOS-User-Token | send it on every run-starting request |
| input too large | > 100k chars | < 60k; fetch context via MCP |
| 404 on /service/runs | SA execution not enabled on env | use /execute |
| Every 2nd turn answers turn 1 (old ACP) | SDK read oldest message | keep newest message only / migrate to A2A |
| Prefetch answer shown as next reply | prewarm on chat thread | never prewarm the chat's thread |
Models, tools, knowledge
| Symptom | Cause | Fix |
|---|---|---|
MODEL_UNAUTHORIZED |
caller lacks llm scope or model not served | llm:model:*, served model, no vendor prefix |
| Answer from a different model than asked | silent fallback | disable_fallbacks; check x-litellm-model-group |
LLM Gateway URL is missing |
context lacks gateway_url | fall back to LLM_GATEWAY_URL env |
MissingExecutionTokenError |
code ran outside NovaOS | NovaOS features only work in a NovaOS run: publish, install, novaos_test_deployed |
| 400 prompt injection detected | gateway filter | reword prompt |
| -32042 approval_required | write-named MCP tool in a user run | read-named tools + returned writes; SA tool grant |
| -32601 tool not found / category mismatch | wrong FQN, inactive MCP, or mcp:tools scope category |
<publisher>.<server>.<tool>; activate; scopes |
| RAG scope mismatch | caller lacks rag scopes | rag:query rag:collections:read |
| RAG 400 on document_ids / query | schema drift | filters.document_ids, question |
| Ingest "completed" but 0 chunks | duplicate upload bug | resolve by content hash |
query 504 at 30 s |
S2S timeout | use search + rerank |
| Search returns irrelevant hits | flat fused scores, top_k always filled | rerank; never threshold |
| Collection not found | stale/other-env id | list collections, use stored id |
When it is NovaOS's fault
5xx responses, responses that break the documented shape, execute answered without a run_id, dispatch failures that persist on fresh threads, RAG internal_error, scan/approval pipelines stuck for hours. Collect: env, time (UTC), request id / run id / agent id / instance id, exact request (no secrets), response. Draft with novaos_report_bug and file it in ClickUp (GS - NovaOS > NovaOS Backlog/Bug List).