Troubleshooting
This page is for developers whose connection, command, hook, runner or embed doesn't do what they expect. Find what you see in the tables below: each row says why it happens and what to do, and links the page that owns the fix. Every message quoted here is checked against the code when the page is built.
Start with a check
Most problems with an agent show up in one command. Run it in the project's folder, as the user the agent runs as:
instruction agents check It checks the sign-in to instruction.md and the instruction the project follows, the agent's app (Claude Code or Codex) and its sign-in, and each MCP server the instruction names. Each line starts with ✓ (fine), ! (a warning) or ✗ (this stops the agent), and a fix: line gives the command that fixes it. It exits 1 when something stops the agent, and 0 otherwise.
$ instruction agents check --host claude-code
✓ signed in; this project follows acme/support-agent (v7)
✓ Claude Code 2.1.330, signed in
Nothing stops the agent. $ instruction agents check --host claude-code
✗ not signed in to instruction.md
fix: instruction agents login (instruction agents login --device on a machine with no browser), or INSTRUCTION_MD_TOKEN
✗ Claude Code isn't installed here (`claude` didn't run)
fix: npm install -g @anthropic-ai/claude-code
Something above stops the agent: fix it, then run `instruction agents check` again.
$ echo $?
1 Outside a project that follows an instruction, not signed in to instruction.md is a warning (!), not a blocker.
On a machine where nobody is there to answer a sign-in, add --fleet: a server that would ask a person to sign in then stops the agent instead of warning.
$ instruction agents check --host claude-code --fleet
✓ signed in; this project follows acme/support-agent (v7)
! the instruction's 1 server(s) and 0 skill(s) aren't written here yet
fix: instruction agents apply --host claude-code
✓ Claude Code 2.1.330, signed in
✗ wiki: wiki.example.com needs a sign-in, and nobody is here to give it
fix: instruction agents signin wiki --url https://wiki.example.com/mcp
Something above stops the agent: fix it, then run `instruction agents check` again. For a script, --json prints the same findings, and --no-probe skips calling each server:
instruction agents check --fleet --no-probe --json {
"ok": false,
"findings": [
{
"kind": "instruction-md",
"name": "instruction.md",
"level": "block",
"what": "not signed in to instruction.md",
"fix": "instruction agents login (instruction agents login --device on a machine with no browser), or INSTRUCTION_MD_TOKEN"
}
]
} To see who the server says you are, run instruction whoami. Every flag of check is on instruction agents commands.
| What you see | Why | What to do |
|---|---|---|
signed in (no project here follows an instruction) |
No .instruction/follow.json in this folder or above it, up to the repository's root. |
Run it in the project's folder, or pass --dir <project>. To set one up, see How following works. |
the followed instruction can't be read: … |
The follow file names an address that doesn't exist, or one you can't read. | Check follow in the follow file and your access with instruction get <address>. |
the servers and skills written here are an earlier version's |
A newer version names other servers or skills than the ones written into the app's files. | Run instruction agents apply. See Servers, skills and accounts. |
<app> <version> isn't signed in |
The agent's app has no sign-in of its own on this machine. | Run the fix: line, as the user the agent runs as. |
Connecting to the MCP server
| What you see | Why | What to do |
|---|---|---|
HTTP 401 with authentication required and WWW-Authenticate: Bearer resource_metadata="…" |
The request carried no token. Every request to /mcp needs one, discovery and lists included. |
Let the host follow the challenge and sign in, run instruction login, or send an agent's token. See Sign-in, scopes and tokens. |
HTTP 401 with error="invalid_token" |
The token expired, or it was issued for another server or by another issuer. | Refresh it, or sign in again. An agent's token lasts five minutes and has no refresh token: ask for a new one. See Agent credentials. |
HTTP 400 with JSON-RPC -32022 or -32600 |
The client speaks the session protocol: an initialize, an Mcp-Session-Id header, or a 2025 protocol version. The server speaks MCP 2026-07-28 only. |
Upgrade the host, or connect it through the stdio server, instruction mcp. See Connect an MCP client. |
| HTTP 405 | A GET or DELETE on /mcp with a token. Without one, the answer is the 401 above. |
Send every request as a POST. |
connect …: the server doesn't speak MCP 2026-07-28 (it offers …) |
The address points at another server, or an older one. | Check --url, INSTRUCTION_MD_URL and the follow file's url. |
claude mcp add connects, then every call fails |
Claude Code runs its v1 MCP runtime (MCP_SDK_GENERATION=v1), which can't speak 2026-07-28. |
Unset the variable, or add the stdio server instead. See Claude Code. |
The orgs_* tools are missing from tools/list |
The token has no org:admin, or it is an agent's. No agent or service credential can have it. |
Sign in again asking for org:admin (people only), or run instruction login --admin. See org:admin. |
invalid_scope when a host signs in |
The host's client named its scopes when it first connected, without org:admin, and now asks for it. |
Remove the connector and add it again, naming org:admin. |
instruction.md refused the permissions this sign-in asked for … from instruction login |
The CLI asked for a scope its client doesn't have, usually an old CLI. | Update the CLI (npm i -g instruction.md), then sign in again. |
scope_required, "this needs a wider scope on your token" |
The person limited the host when they connected it, or the agent's credential has fewer scopes. | The person allows more under Your account ▸ Connected apps. An agent needs a new credential with the scope: scopes can't be added to one. |
Sign-in timed out: nothing came back from the browser in 5 minutes. |
The browser never reached the CLI's address on this computer, for example over SSH. | Run instruction login --device and enter the code on any device. |
JSON-RPC -32025 with limit_reached in data |
Another consumer holds the plan's live updates. Reading still works. | Keep reading, and ask again after data.details.retryAfterSeconds. See The live-updates limit. |
JSON-RPC -32020 |
An events/* request without an Mcp-Name header, or with one that differs from params.name. |
Send the event's name in Mcp-Name. See Live updates. |
| HTTP 429 | One of your rate-limit buckets is empty. | Wait, then call again with a growing pause. See Rate limits. |
Every refusal the gateway answers before a tool runs is on Errors.
Errors from a tool call
A refused tool call answers isError: true with a code, a message and details. Branch on the code. Every code is on Errors.
| What you see | Why | What to do |
|---|---|---|
version_conflict |
The draft, or the thing you edit, changed since you read it. | Read again with the call in details.reread, and make your change on what you read. Never resend the same change with only the revision changed. See Expected revisions. |
needs_confirmation |
The call changes what others receive, or can't be undone. Nothing changed yet. | Show summary and consequences to the person, and call again with confirmToken only if they agree. A program never confirms for a person. See Needs confirmation. |
validation with details.reason mismatch, expired, used or invalid |
The confirming call's tool, caller or arguments differ from the first call's, more than 10 minutes passed, the token was used, or this server didn't give it. | Call again without the token and ask the person again. |
this confirmToken is for a different call through a sealed company proxy |
The confirming call reached another replica of the proxy, or came after the 4 minutes the proxy keeps the sealed text. | Ask for the change again and confirm promptly. See Sealed instructions for developers. |
conflict, "this idempotency key was used for a different call" |
One key on two different calls. | Use a new key for each distinct call. See Idempotency keys. |
conflict, "nothing changed since the latest version" |
The draft's accepted text equals the latest version. | Change the draft first. A Contributor's or an agent's edits are suggestions until a Maintainer accepts them. |
not_found |
It doesn't exist, or you can't see it. A private instruction answers the same as one that was never made. | Check the address and your access. |
forbidden |
Your role or the organization's policy doesn't allow it, for example agentPublish for an agent's release. |
Ask someone with the role. See Policy and roles. |
limit_reached |
A plan limit, such as private instructions or versions a month. details names the limit and the tool that upgrades. |
See Rate and size limits. |
isError: true with Input validation failed for tool '…' and no structuredContent |
The arguments don't fit the tool's inputSchema, such as an argument it doesn't take. |
Fix them against tools/list. The CLI shows it as invalid_input and exits 2. |
unavailable or internal |
A race, a timeout or a fault on the server's side. | Retry with a growing pause. A call with an idempotencyKey is safe to send again. |
The instruction CLI
The registry commands of instruction exit with these codes, as instruction --help lists them:
1: error2: usage or a refused input3: transport or not signed in4: not found5: forbidden6: nothing applied7: not confirmed
A refusal from the server prints tool: code: message on standard error and exits by its code:
- invalid_input (the gateway's input-schema refusal): exit 2
not_found: exit 4forbidden: exit 5unauthenticated: exit 3- every other code: exit 1
| What you see | Why | What to do |
|---|---|---|
… (this registry needs a signed-in caller: run `instruction login`, or pass --token), exit 3 |
No sign-in, or it ran out and couldn't be refreshed. | Run instruction login, or set INSTRUCTION_MD_TOKEN. In CI, ask for the token in the same job, just before the commands. |
| You are signed in on your machine, but not in a container or a CI job | XDG_CONFIG_HOME or the home folder differs from where you ran instruction login. |
Point XDG_CONFIG_HOME at the folder with instruction-md/credentials.json, or pass a token. See Environment and files. |
instructions_publish: this asks first; nothing changed (run again with --yes to go ahead), exit 7 |
The release asks first, and a CI job has no terminal to ask on. | Add --yes. See Publish and check from CI. |
cancelled; nothing changed, exit 7 |
You answered something other than y or yes. |
Run it again and answer y. |
The first release ends with (say it with --visibility private, internal or public), exit 2 |
The first version of an instruction must say who reads it. | Add --visibility private (or internal, public). |
--sign-with: …, exit 2 |
This server signs every version with the organization's key. Your own keys can't sign versions here. | Release without --sign-with. See Signing with your own key. |
`instruction keys …` administers an organization, which takes one more permission … |
Your sign-in lacks org:admin. On a terminal the CLI offers to sign in again; without one it exits 3. |
Run instruction login --admin once, then the command again. |
instruction watch --once exits 6 |
It applied nothing: the version was held, or nothing could be read. | Read the hold: line on standard error. See Holds. |
instruction test passes, but some vectors weren't run |
It runs the source, resolution and text vectors only, and says nothing of model-cases.json, policy-cases.json or workflow-cases.json. |
Run those with your own harness. See Evals and tests. |
Hooks and following
How a hook reads, caches and holds is on How following works. These are the hooks' own lines, as the agent's app shows them, and what to do about each.
| What you see | Why | What to do |
|---|---|---|
| Nothing at a session's start in Claude Code | The project and its hooks aren't trusted yet, or the session started before the setup. | Start a new session, trust the project when Claude Code asks, and check that /hooks lists the two hooks. |
| Nothing at a session's start in Codex | Codex runs a project's hooks only in a trusted project, and asks to trust each hook again when its command changes. | Trust the folder, then the hooks in /hooks. See Trust the hooks. |
| Nothing, in a subfolder or a second repository | A hook looks for .instruction/follow.json from the session's folder up to the repository's root (the folder with .git), and no further. |
Start the app inside the project, or set it up in that repository too. |
| The first session on a machine has no instruction, or the hook timed out | npx -y @instruction.md/agents downloads the package on its first run, and the hooks' timeouts are 10 seconds at a session's start and 5 at a prompt. |
Install the package and set up again with --cli instruction-agents (below). |
instruction.md: couldn't read <instruction> (…); this session goes on without it |
The hook got no text and has no copy yet: no sign-in, no network, or a ref that doesn't exist. | Run the check. Sign in with instruction agents login, check the address, and create the ref if it is stable. |
… is not public here (a private one is read signed in: instruction login) |
You are signed out, and the instruction isn't public. | Run instruction agents login. |
instruction.md: <instruction> couldn't be read now (…); using the last good copy, v4 |
Offline, slow, or the sign-in was refused. The hook waits at most 1.5 seconds. | Nothing breaks: it tries again at the next prompt. Sign in again if the sign-in lapsed. See Offline. |
instruction.md: a newer version of <instruction> is held (…); keeping v4 |
The follower refused the new version and keeps the one it has. | Read the reason in the brackets. See Holds. |
instruction.md: this project follows <instruction>, and no copy of it could be read (…)., and the session stops or the prompt is blocked |
The hook runs with --fail-closed, and there is no copy at all. |
Fix the read (the first rows), or remove --fail-closed where a session may run without the instruction. |
….claude/settings.json is not JSON (…); fix it, or add the hooks by hand, exit 2 |
The settings file can't be parsed, so the setup wrote nothing. | Fix the file and set up again, or add the two hooks by hand. |
| Every read times out behind a proxy | The hook reads with Node.js's own fetch, which uses HTTPS_PROXY only when NODE_USE_ENV_PROXY=1 is set. |
Set both where the app starts. See Offline machines, proxies and Node. |
| The agent has only part of a long instruction | A hook puts at most maxInjectChars (9,000 by default) into the conversation at once, with a line to read .instruction/current.md. |
Raise maxInjectChars in the follow file. See follow.json. |
| The Agents card doesn't show a machine | The hook isn't signed in, or its report didn't fit in the hook's time. | Sign in. The report is sent again at the next event. |
Install the agents' package so a hook never waits for a download:
npm i -g @instruction.md/agents
instruction agents follow acme/support-agent@stable --host claude-code --write --cli instruction-agents To see what a hook gives the agent, run it by hand with the event its app sends:
echo '{"hook_event_name":"SessionStart","source":"startup","cwd":"'"$PWD"'"}' | instruction agents hook claude-code Holds
A follower that can't apply a new version keeps the last good one and reports a hold. A hold is not an error from the server. instruction watch prints it as hold: <reason> (keeping <version id>), and the hooks as the is held line above. The reasons you meet most:
| The reason | Why | What to do |
|---|---|---|
version ver_… is unsigned |
requireSignature is on and the version has no author signature. A sealed version has no platform signature. |
Release it from a server that signs. For a sealed instruction, don't require a platform signature. |
signature rejected: … |
No key verifies the signature, or the text isn't the one signed. | Don't apply it. Read the keys again, and report it to the publisher. |
version ver_… is signed with a revoked key (…) |
Its key was revoked. | Move the ref to a version signed with an active key. |
no publisher keys to verify ver_… (…) |
The read named no key list, and you gave none. | Sign in so the keys can be read, or pass --keys. |
publisher … is not the pinned … |
Another publisher signed it. | Check --publisher. A renamed organization signs older versions with its old slug. |
sealed: this instruction is encrypted, and this machine has no key for it (…) |
The instruction is in a sealed workspace, and no key is set here. | Set INSTRUCTION_MD_SEAL_KEY_FILE, INSTRUCTION_MD_SEAL_KEY_COMMAND or INSTRUCTION_MD_SEAL_PASSPHRASE. See Sealed instructions. |
Every hold the follower can give is listed, from its code, on Errors. What each one means for signatures is on Signing and verification.
Sealed instructions
| What you see | Why | What to do |
|---|---|---|
Answers show a JSON object with "seal":"imd-seal/1" |
The client that read it holds no key, so it got the envelope. | Read it through instruction-mcp with a key, or set a key for the CLI's followers. |
this key doesn't hold workspace ws_…'s key yet |
The key wasn't given the workspace's key, or not at this epoch. | Someone who holds it gives it: Give the key in the editor, or seal_wraps_add. |
instruction-mcp key status says not unlocked here |
No key file is given, or a passkey-only key can't unlock outside the browser. | Pass --key-file, add a passphrase under Your account ▸ Security ▸ Encryption key and set INSTRUCTION_MD_SEAL_PASSPHRASE, or use INSTRUCTION_MD_SEAL_RECOVERY. |
forbidden, … is sealed: instruction.md can't read it, so … runs where it is unlocked … |
A tool that runs on the server met a sealed instruction. | Do it in the editor, or through instruction-mcp. |
The other messages are on Sealed instructions for developers.
The runner
instruction agents run exits 0 when it stops normally, 1 when a --once pass had an agent fail, 2 on a usage error, 3 when it isn't signed in or can't reach the server on its first read, 4 when --org names no organization of yours or the rule doesn't exist, and 5 when its first read is refused. Each agent is reported as ok, failed or needs_sign_in. Both are on Exit codes and states.
| What you see | Why | What to do |
|---|---|---|
instruction agents run reads your organization's deployments: sign in first (`instruction agents login`, or --token), exit 3 |
No sign-in for this user. | Run instruction agents login --device as the user the runner runs as. |
no organization acme among yours (…), exit 4 |
--org isn't one of the signed-in person's organizations. |
Check the slug, or sign in as a member. |
<deployment>: not started, it needs: … |
A sign-in is missing for the agent's app or one of its servers. | Run the fix it prints, as the runner's user. The next pass starts the agent. |
| Needs sign-in on Settings ▸ Deployments | The same, as the editor shows it. The report lists what is missing and the command that gives it. | Run that command on the machine, as the runner's user. Then run the check with --fleet. |
| Behind on Settings ▸ Deployments | The agent runs an older version than its rule says: a version waits for approval, or a live agent hasn't had its next turn. |
Approve the version, or wait for the agent's next turn. |
fleet: its agents' questions can't reach instruction.md: … |
Claude Code isn't run as claude -p "…", or the command already sets --input-format or --output-format. |
Give the task as claude -p "…" without those flags. See Conversations. |
| Remote Control doesn't start | It needs a claude.ai sign-in on a plan with Remote Control (not an API key), Linux or macOS, and a runner that keeps running. | See Remote Control. |
Servers, skills and accounts
| What you see | Why | What to do |
|---|---|---|
(not set up: … is larger than 256 KB) |
A skill's file is over the limit. | Shorten it, or split it into two skills. |
… doesn't match the sha256 the instruction gives (it changed since it was named): not written |
The skill's file changed at its source. | Check the change, then update sha256 in the instruction and release. |
(left alone, not ours: .mcp.json: desk) |
Someone else wrote a server of the same name. | Rename one of them, or remove the other entry and apply again. |
the sign-in to desk@work lapsed and couldn't be renewed (…) |
Its refresh token was refused. | Run the fix it prints, instruction agents signin desk --account work --url …. |
Every message is on Servers, skills and accounts.
Embedding an instruction
| What you see | Why | What to do |
|---|---|---|
| The document shows as plain text | The renderer's script didn't load: it was blocked, or your Content-Security-Policy doesn't allow it. | Allow script-src https://instruction.md. See A strict Content-Security-Policy. |
Failed to fetch, or registry 401: …, on an element with ref |
The renderer reads ref with an anonymous resources/read. Every request to /mcp needs a sign-in, and its CORS headers allow only instruction.md's own pages. |
For a public instruction, load its web address with src instead (below). It needs no sign-in. See Why not ref. |
refusing to fetch …: origin not allowed (set allow-origins) |
src reads only from your own site, instruction.md, the registry and the hosts in allow-origins. |
Add the host to allow-origins. |
document exceeds max-bytes (…) |
The document is over max-bytes, 1 MiB by default. |
Raise max-bytes on the element. |
| Instruction code fences stay as code | The script tag has no data-fences. |
Add data-fences, or data-watch for a live preview. |
| Images show as placeholders | Images are off until the element has allow-images. |
Add allow-images if you accept that each image is a request to its server. |
A pinned render@<version> file with integrity doesn't load |
A browser checks integrity on another site's script only when that site sends CORS headers, and these files don't yet. | Serve the pinned file from your own site with the same integrity. See Pin with Subresource Integrity. |
<script src="https://instruction.md/render@1.classic.js" defer></script>
<instruction-md src="https://instruction.md/acme/support-agent@stable"></instruction-md> Self-hosting
These come from the local stack, deploy/k8s/stack/up.sh, which runs the production charts in a k3d cluster. The rest is on Self-hosting.
| What you see | Why | What to do |
|---|---|---|
dist/web isn't built for http://localhost:18080 — build it so (pnpm build:web, …), then run this again |
The site and the editor weren't built for the stack's origin. | Build them with the PUBLIC_IMD_* variables deploy/k8s/stack/README.md gives, then run up.sh again. up.sh --web ships a new build alone. |
(this cluster's pods reach no https site: the gateway goes through a proxy on the node) |
The cluster's pods can't reach ghcr.io, where the gateway pulls its plugins. | Nothing: up.sh routes the gateway through a CONNECT proxy on the node. |
| The embedding model doesn't start, or search matches words but not meaning | The model's weights come from Hugging Face, which the machine can't reach. | Run deploy/dev/embeddings.sh once where Hugging Face is reachable. It fetches the weights into deploy/mcpg/data/embeddings, and up.sh serves them offline. |
platform signing is off on this server (unavailable) |
imd-svc has no IMD_SIGNING_MASTER_KEY, so it signs nothing. |
Run deploy/k8s/bootstrap-secrets.sh, which makes the key on its first run and keeps it after. Keep a copy: losing it changes every organization's publisher keys. |
| A second gateway replica in production doesn't cluster | More than one replica, clustered on NATS, needs an MCPG licence. The local stack's free non-production grant covers clustering only outside production. | Run one replica, or get a licence. See Run one gateway without a licence. |
Still stuck
Ask us on Support. Say what you ran, what it printed, the time, and your operating system, and the output of instruction agents check --json if it is about an agent.