Цю сторінку ще не перекладено.

Errors

This page is for developers who call instruction.md's MCP server, from their own code, an agent or the instruction CLI. It lists every error code the server returns, the refusals the gateway answers before a tool runs, the holds a follower reports, and the CLI's exit codes, with what to do about each.

How an error reaches you

A tool that refuses answers a normal tools/call result with isError: true. Its structuredContent is the error, and its text block is the same JSON. The error has three members:

  • code: one of the codes below. Branch on it, never on the message.
  • message: one sentence a person can be shown as it is.
  • details: what a program needs. field names the argument at fault, as a path such as ops[2].from. next says the next step in words a model can follow.
A refused tools/call
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\": {\"code\": \"not_found\", \"message\": \"instruction not found\"}}"
      }
    ],
    "structuredContent": {
      "error": {
        "code": "not_found",
        "message": "instruction not found"
      }
    },
    "isError": true
  }
}

Every tool answers this way, whether it runs in Postgres or in the service. A refused tool call changes nothing: whatever it had written is undone in the same transaction.

A resources/read that the server refuses is a JSON-RPC error instead, code -32603. The same error object is inside its message, after backend returned an error response:. Parse it from there.

A refused resources/read
{
  "jsonrpc": "2.0",
  "id": 8,
  "error": {
    "code": -32603,
    "message": "resource backend produced a non-conforming response: backend returned an error response: {\"error\": {\"code\": \"not_found\", \"message\": \"instruction not found\"}}"
  }
}

The gateway also refuses some requests itself, before any tool runs. Those are listed under Refusals from the gateway.

Error codes

These are the codes the server's domain raises, read from its SQL when this page is built. The SQL raises errors in 490 places, and the service raises the same codes.

CodeWhat it meansWhat details holdsWhat to doCLI exit
not_foundThere is no such thing, or you may not see it. The server answers the same for both, so a private instruction never shows it exists.Usually none. Some name the id or field that was looked up.Check the id, owner/name or address. If it should exist, check that you are signed in as the right person or agent.4
forbiddenYou can see it, but your role, the organization's policy or the caller's kind doesn't allow this.need and have (permissions) with role, or reason (see the reason values), and sometimes policy or appId.Ask someone with the role it needs, or do what you may instead, such as suggesting a change rather than editing.5
unauthenticatedThe call needs a signed-in person or agent, or the account it was made as is deleted.Usually none. A deleted account's has reason account_deleted and next.Sign in (instruction login, or your host's sign-in) and call again.3
validationAn argument is missing, has the wrong shape, or names a value the tool doesn't take. Also a confirmToken that is invalid, expired, used, or for another call.field (the argument at fault, as a path such as ops[2].from), allowed or expected, and sometimes reason, question and next.Fix the argument named by details.field and call again. A question in details is one to put to the person.1
version_conflictWhat you changed moved on since you read it: the revision you sent is not the current one.currentRevision, reread (the tool and arguments, or the resource, to read again) and next.Read it again with details.reread, make your change on what you read, and send it with the new revision. Don't resend the same change.1
conflictThe call can't be done in the state things are in: a name taken, an idempotency key reused for another call, a state that doesn't allow it.field or state, reason, and sometimes next.Read the current state, then choose another name or make the call the state allows. A reused idempotency key needs a new key.1
needs_confirmationNot a failure. The tool changes what others receive or can't be undone, so it asks first and has changed nothing.summary, consequences, confirmToken, expiresIn (600 seconds) and next.Show the person the summary and consequences. Only if they agree, call again with the same arguments plus confirmToken.1
scope_requiredThe token's scopes don't reach this. Either the token was asked for with less, or the person connected the app with less access.scope (the one it needs, such as instructions:publish), and next. An app's has reason consent_required, url and scopes.Sign in again asking for that scope, or have the person allow more under Your account ▸ Connected apps. Organization tools need org:admin.1
limit_reachedA plan limit or feature, a size or count limit, or an overdue payment stops the call. Also live updates that are taken.limit, max, used, orgId, plan and upgrade; or feature and upgrade; or reason past_due with manage; live updates add retryAfterSeconds and reads.Make room, upgrade with the tool in details.upgrade, or wait (retryAfterSeconds). Reading is never limited.1
unavailableThe server can't do this now: a part it needs isn't set up on this server, or the database was busy and gave up.None.Retry after a pause when it was busy. If the message says a part isn't set up, it won't succeed on this server.1
remote_onlyAnswered by the editor's local server, which keeps instructions in a browser before you sign in: the tool needs instruction.md itself.None.Sign in, and move the browser's instructions to your workspace.1
internalSomething broke on the server. The message never carries the database's own words.None.Retry once. If it repeats, report it with the time and the tool you called.1

A few internal functions also raise invalid_argument, which reaches the caller as that code. No tool a customer calls raises it.

remote_only comes only from the editor's local server, which keeps instructions in a browser before anyone signs in. The server itself never answers it.

Errors that start in the database

An error the database raises, rather than the domain, is turned into a code too. The database's own words never reach you.

  • A name or key that must be unique and is already used: conflict, "that name is already taken".
  • A value of the wrong type, out of range, or naming something that isn't there: validation, with details.field naming the argument when it can be found. When it can't: "an argument has the wrong shape: check each against the tool's input schema".
  • A transaction that lost a race, or a lock that timed out: unavailable. Call again.
  • Anything else: internal, "something went wrong on the server".

The reason values

Some refusals carry details.reason, a word a program can branch on. These are every value the SQL writes, by code:

  • not_found: unpublished
  • forbidden: app_off, app_revoked, app_rotated, app_scope, app_unknown, apps_off, email, owner, sealed, second_person, system_org, template_service, unverified
  • unauthenticated: account_deleted
  • validation: default, expired, invalid, mismatch, sealed, used
  • conflict: account_changed, cooling_off, default, expired, last_owner, not_empty, revoked, sole_owner
  • scope_required: consent_required
  • limit_reached: past_due, rate

A few to know:

  • forbidden with apps_off, app_unknown, app_revoked, app_rotated, app_off or app_scope is a call through an app a person connected. Apps can only read released versions and change nothing.
  • scope_required with consent_required is an app the person hasn't yet allowed: details.url is the page where they allow it.
  • limit_reached with past_due is an organization whose payment is overdue. details.manage names orgs_billing_portal.
  • validation with invalid, expired, mismatch or used is about confirmToken. Call again without it and ask the person again. See Contracts.

An error body for each code

Each sample is the structuredContent of a refused call. The messages are the server's own words, checked against its code when this page is built.

not_found
{
  "error": {
    "code": "not_found",
    "message": "instruction not found"
  }
}
forbidden
{
  "error": {
    "code": "forbidden",
    "message": "this needs edit on the instruction; you have read",
    "details": {
      "need": "edit",
      "have": "read",
      "role": "reader"
    }
  }
}
unauthenticated
{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to do this"
  }
}
validation
{
  "error": {
    "code": "validation",
    "message": "instructionId is required",
    "details": {
      "field": "instructionId"
    }
  }
}
version_conflict
{
  "error": {
    "code": "version_conflict",
    "message": "the draft changed since you read it: it is at revision 15 now",
    "details": {
      "currentRevision": 15,
      "reread": {
        "tool": "instructions_get",
        "arguments": {
          "include": [
            "draft"
          ],
          "instructionId": "ins_01JD8Q5V0YB3X2K7M9N4P6R8ST"
        }
      },
      "next": "Read it again (instructions_get {\"include\": [\"draft\"], \"instructionId\": \"ins_01JD8Q5V0YB3X2K7M9N4P6R8ST\"}), make your change on what you read, and send it with expectedRevision 15."
    }
  }
}
conflict
{
  "error": {
    "code": "conflict",
    "message": "this idempotency key was used for a different call",
    "details": {
      "idempotencyKey": "publish-acme-support-agent-7"
    }
  }
}
needs_confirmation
{
  "error": {
    "code": "needs_confirmation",
    "message": "Release v3 of Support agent as latest?",
    "details": {
      "summary": "Release v3 of Support agent as latest?",
      "consequences": [
        "2 agent(s) following latest switch to v3."
      ],
      "confirmToken": "<token>",
      "expiresIn": 600,
      "next": "Show the person the summary and the consequences, and ask them. Only if they agree, call instructions_publish again with the same arguments plus this confirmToken: it works for 10 minutes, for this call by you alone (sent again, the call answers what it did). If they don't agree, do nothing more: nothing has changed."
    }
  }
}
scope_required
{
  "error": {
    "code": "scope_required",
    "message": "this needs a wider scope on your token",
    "details": {
      "scope": "instructions:publish"
    }
  }
}
limit_reached
{
  "error": {
    "code": "limit_reached",
    "message": "this plan keeps 3 private instructions; make one public, delete one, or upgrade",
    "details": {
      "limit": "privateInstructions",
      "max": 3,
      "used": 3,
      "orgId": "org_01JD8Q4ZK3W5Y7A9C1E3G5J7M9",
      "plan": "community",
      "upgrade": "orgs_billing_checkout"
    }
  }
}
unavailable
{
  "error": {
    "code": "unavailable",
    "message": "search by meaning isn't set up on this server; instructions_list {query} searches the words"
  }
}
remote_only
{
  "error": {
    "code": "remote_only",
    "message": "instructions_publish needs instruction.md: sign in, and move this browser's instructions to your workspace there"
  }
}
internal
{
  "error": {
    "code": "internal",
    "message": "something went wrong on the server"
  }
}

A limit_reached refusal at a plan limit names the limit, the plan's figure, what the organization holds and the tool that upgrades it. Every limit and its refusal is on Rate and size limits. needs_confirmation is not a failure: how to answer it is on Contracts.

Refusals from the gateway

The gateway in front of the server answers these itself, before a tool runs. Most are JSON-RPC errors, not tool results.

What you getWhyWhat to do
HTTP 401, {"error":{"code":-32000,"message":"authentication required"}}, and WWW-Authenticate: Bearer resource_metadata="…"The request on /mcp carries no token. Every request needs one, discovery and lists included.Sign in. The header names the protected-resource metadata, which names the authorization server. See Sign-in, scopes and tokens.
HTTP 401 with error="invalid_token"The token doesn't verify: it expired, or it is for another server.Refresh it, or sign in again.
HTTP 400, JSON-RPC -32022 or -32600A request on the session protocol: an initialize, an Mcp-Session-Id header, or the version 2025-11-25.Speak MCP 2026-07-28, which has no session. A host that can't connects through instruction mcp. See Connect an MCP client.
HTTP 405A GET, HEAD or DELETE on /mcp.Send every request as a POST.
JSON-RPC -32020An events/* request without an Mcp-Name header, or with one that differs from its params.name.Send Mcp-Name with the event's name, as on Live updates.
JSON-RPC -32602The request's params are refused, such as a call of a tool that isn't there, or of the gateway's internal admission tool, realtime_admit, which no caller may call.Check the method's params. Call only the tools tools/list shows you.
A result with isError: true and the text Input validation failed for tool '…', no structuredContentThe arguments don't fit the tool's inputSchema, such as an argument it doesn't take.Fix them against the schema in tools/list. The CLI shows this as invalid_input and exits 2.
JSON-RPC -32025Live updates are refused. When its data is a limit_reached error, another agent holds the plan's live updates.Keep reading, and ask again after data.details.retryAfterSeconds. See The live-updates limit.
JSON-RPC -32603 on a stream or subscription, "retry later"The gateway couldn't ask whether you may hold live updates (the database didn't answer), so it refused.Reconnect with a growing pause, from the last cursor you have.
HTTP 429One of your rate-limit buckets is empty.Wait, then call again. See Rate limits.
An input-schema refusal
{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Input validation failed for tool 'instructions_get': arguments validation failed: Additional properties are not allowed ('bogus' was unexpected). Inspect the tool's inputSchema via tools/list and retry."
      }
    ],
    "isError": true
  }
}

The gateway also checks each answer against the tool's outputSchema, and fails a call whose answer doesn't fit rather than pass it on. That is a fault on the server's side: report it with the tool's name and the time.

Handling errors in your client

  • Branch on code. Show message to a person as it is. Read details.next when a model decides the next step.
  • needs_confirmation: never send the confirmToken back on the person's behalf. Show the summary and consequences, and call again only if they agree.
  • version_conflict: read again with details.reread, make your change on what you read, and send details.currentRevision. Sending the same change again with the new revision overwrites what someone else did.
  • unavailable, internal and the 5xx and 429 answers: retry with a growing pause. A call with an idempotency key is safe to send again. See Contracts.
  • not_found doesn't tell you whether something exists. A private instruction you can't see answers the same as one that was never made.
Reading a refusal (TypeScript)
// result: the "result" member of a tools/call answer
function refusal(result) {
  if (!result.isError) return null;
  const error = result.structuredContent?.error;  // { code, message, details }
  // no error object: the gateway refused before the tool ran (an input-schema refusal, for one)
  return error ?? { code: "invalid_input", message: result.content?.[0]?.text ?? "refused" };
}

const error = refusal(result);
if (error?.code === "needs_confirmation") {
  // show error.details.summary and error.details.consequences; only if the person agrees,
  // call again with the same arguments plus confirmToken: error.details.confirmToken
} else if (error?.code === "version_conflict") {
  // read again (error.details.reread), redo the change, send error.details.currentRevision
} else if (error) {
  throw new Error(`${error.code}: ${error.message}`);
}

Holds

A follower that reads a new version and can't apply it keeps the version it has, and reports a hold. A hold is not an error from the server: the read succeeded, and the follower refused the version, or the read failed and it keeps the last good one. What a follower does then is on How following works.

These are the holds the TypeScript follower reports, read from its code. It is the follower behind instruction watch and the instruction.md library. In the messages, <…> is a value and […] is said only when there is one.

The holdWhyWhat to do
read failed (<reason>): <message>The read itself failed: offline, a refused or expired token, past a deadline, or not found (deleted, or no longer visible to you).Check the connection and the sign-in (instruction login). The last good version stays applied meanwhile.
empty readThe server answered the read with no text.Read the address again; if it stays empty, report it.
read carried no md.instruction/versionIdThe answer isn't a released version: an address that isn't one, such as the draft or a view.Follow instruction://<owner>/<name>, an @ref, or a pinned @vN or @ver_… address.
version <versionId> exceeds <maxBytes> bytesThe version is larger than the follower's maxBytes policy.Raise maxBytes, or shorten the instruction.
publisher <publisher> is not allowedThe version's publisher isn't in the follower's allowedPublishers.Add the publisher (https://instruction.md/pub/<owner>) to allowedPublishers, or follow another instruction.
version <versionId> was revoked[: <reason>]A pinned read of a version its maintainers revoked. Refs never point at a revoked version.Pin another version, or follow a ref.
publisher <publisher> is not the pinned <publisher>The version's publisher isn't the one the follower pins (--publisher).Check the owner: an instruction moved to another organization is published by it now.
version <versionId> carries no delivery signatureThe follower requires a delivery signature (--require-delivery-signature) and the server gave none for this version.Sign in as the reader the delivery is for, or drop the requirement.
no keys to verify the delivery of <versionId>No delivery keys or no publisher keys could be read to check the delivery signature.Check that instruction://delivery-keys.json and the publisher's keys.json can be read, or pass the keys.
delivery signature rejected: <reason>The delivery signature doesn't verify over the bytes received, for this reader.Don't apply it. Read again; if it repeats, report it with the version id.
version <versionId> is unsignedThe follower requires a signature (--require-signature) and the version has none.Publish a new version: every version is signed with the organization's platform key.
version <versionId> is signed with a revoked key[ (<kid>)]The key that signed the version was revoked.Publish a new version, which is signed with the current key.
no publisher keys to verify <versionId> (pass authorKeys or let the registry publish keys.json)The publisher's keys (instruction://pub/<owner>/keys.json) couldn't be read, or list no key in force.Pass the keys (--keys FILE) or let the follower read keys.json.
signature rejected: <reason>The version's signature doesn't verify against the publisher's keys.Don't apply it. Read again; if it repeats, report it with the version id.

instruction watch prints each hold on stderr with the version it keeps. With --json it prints one JSON line:

instruction watch
hold: version ver_01JD8R2M4P6T8V0X2Z4B6D8F0H is unsigned (keeping ver_01JD8Q9K1M3P5R7T9V1X3Z5B7D)
{"event":"hold","reason":"version ver_01JD8R2M4P6T8V0X2Z4B6D8F0H is unsigned"}

CLI exit codes

The registry commands of instruction exit with these codes, as instruction --help lists them:

  • 1: error
  • 2: usage or a refused input
  • 3: transport or not signed in
  • 4: not found
  • 5: forbidden
  • 6: nothing applied
  • 7: not confirmed

A refusal from the server prints tool: code: message on stderr and exits by its code:

  • invalid_input (the gateway's input-schema refusal): exit 2
  • not_found: exit 4
  • forbidden: exit 5
  • unauthenticated: exit 3
  • every other code: exit 1
A refusal at the terminal
$ instruction publish acme/support-agent
instructions_publish: forbidden: this needs publish on the instruction; you have suggest
$ echo $?
5

A command that asks first, such as instruction publish, exits 7 when you don't agree, or when there is no terminal to ask on and no --yes. Nothing changes then. instruction watch --once exits 6 when it applied nothing. All commands are on The instruction CLI.

Last checked against the product:

Was this page helpful? Report a problem