Troubleshooting

Most nax failures come from missing CLI authentication, ambiguous project selection, prompt-size limits, or stale local state. Start with the exact command you ran, then check whether the failure happened before submission, while waiting for agents, or while reading artifacts afterward.

Required CLIs are missing

gh auth login
netlify login

nax does not provide its own browser auth flow for those tools.

Could not resolve NETLIFY_SITE_ID

netlify link
nax init --site-id <site-id>
nax init --site-name <site-name>

For multi-project repositories, run from the app directory or pass the needed filter/config option.

No runnable transport detected

nax init
nax run review --transport netlify-api

Pinned SHA not on remote

git push
nax run review --no-auto-context

Agent run times out

nax run review --timeout-minutes 45

Long synthesis steps often need more time than first-round audit steps.

Prompt is too large

unset NAX_PROMPT_BLOB_DISABLE
NAX_SAFE_PROMPT_BYTES=32768 nax run review

For netlify-api runs, nax-agent-runner-sdk measures the final request-marker-decorated UTF-8 prompt. It sends the prompt inline when safe. When the prompt is oversized and site-scoped storage is available, NAX stores the complete prompt in a Netlify Blob and submits a small fetch wrapper. Deterministic compaction is used only when blob delivery is disabled or unavailable. The SDK returns prompt-too-large only when no configured path fits. Confirm that the selected site is correct and that NETLIFY_AUTH_TOKEN can access it before increasing the budget.

prompt-ref-expired means a retained failed-run reference reached its expiry before a resume or retry. Start a fresh run so the SDK can upload a new prompt; never edit the serialized handle or reuse the expired key.

SDK-owned blobs are deleted after success, cancellation, or timeout. A failed run retains its blob for diagnosis and safe retry until the reference’s logical expiry. Netlify Blobs does not delete it automatically at that time; consumers that may abandon failed handles must sweep expired SDK entries separately. Run artifacts contain the store/key/tenant/expiry and sentinel, but never the token or fetch command. Local mirrors under .nax/workflows/<run-id>/blobs/ apply to the GitHub issue/comment compatibility transport.

Resume or sync state

nax run --retry <run-id>
nax admin sync last
nax admin clean blobs

Dashboard unauthorized

Reopen the exact URL printed by nax dashboard. Mutating endpoints require the per-process token query value or an x-nax-token header.

Dashboard fallback HTML

npm run dashboard:build

The published package should include src/dashboard/web/dist; source checkouts need a local build.

MCP control plane

Start with the read-only diagnostic:

nax mcp doctor

dashboard_not_running

Start the control plane in the project named by the error. Cross-project errors include the exact root:

nax dashboard --project-root '/workspace/gtm-services' --no-open

The MCP child discovers the new process and port on its next call. You do not need to rewrite .mcp.json or restart Claude.

dashboard_unreachable or dashboard_timeout

The advertised process is alive but its loopback API did not answer. Stop and restart the dashboard, then retry the same read. Do not copy a token or port into MCP arguments.

dashboard_auth_failed

The private registry token and dashboard process no longer agree. Restart the dashboard so both are replaced together. Registry files with symlink or broad permission problems are rejected rather than trusted.

dashboard_version_mismatch

Claude’s nax mcp child and the dashboard came from different NAX versions. Restart both from the same installed package. A running MCP process never silently talks to a mismatched dashboard.

project_scope_mismatch or scope_forbidden

The supplied scope is unknown, stale, or did not match the selected dashboard. Call context_get with the intended absolute project_ref, verify the returned project and Netlify target, then copy its exact scope_id into the next call. Tools cannot override the selected site or actor.

project_not_found or project_ambiguous

Use an exact absolute directory in context_get.project_ref. Short project, repository, and site aliases resolve only against currently running dashboards and are never fuzzy-selected. For an ambiguous alias, choose one returned scope_id. For a missing alias, start that project’s dashboard and retry.

no_token, bad_token, no_site, or no_access

These errors concern the selected Netlify target, not the private dashboard token:

netlify login
netlify link
nax mcp doctor

Confirm the exact site reported by context_get before planning again.

Agent, model, or capability errors

Call context_get again and choose exact agent, model, and effort IDs from its catalog. If a capability is unavailable, follow its reason and use only tools marked available for the current runtime. Desktop and hosted runtimes are future-compatible but are not shipped yet.

run_plan_expired

Create a fresh workflow_plan or agent_run_plan, review its target and runner count, then start the new plan. An expired plan cannot be extended at start time.

Duplicate, conflicting, or uncertain starts

Retry an uncertain run_start with the same plan_id and request_id; NAX returns the original durable run. idempotency_conflict means that key was already used for different intent, so review the change and generate a new request ID. duplicate_run points to the existing run you should inspect or wait on.

Ambiguous or stale control targets

Call run_get with view: "details" and copy one exact current agent_run_id, review_gate_id, or artifact ID. NAX intentionally rejects provider names, URLs, wildcards, and broadcast targets.

See also

• Get started for first-run setup.
• Configuration reference for environment variables.
• Artifacts for recovery and handoff paths.
• Use NAX with Claude for setup and safe operation.
• MCP reference for the complete tool and resource surface.