NovaOS MCP
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).