Skip to content

SEP-2164: Standardize resource not found error code (-32602)#2164

Merged
mcp-commander[bot] merged 9 commits into
mainfrom
sep/resource-not-found-error
May 18, 2026
Merged

SEP-2164: Standardize resource not found error code (-32602)#2164
mcp-commander[bot] merged 9 commits into
mainfrom
sep/resource-not-found-error

Conversation

@pja-ant

@pja-ant pja-ant commented Jan 28, 2026

Copy link
Copy Markdown
Contributor

This SEP standardizes the error code for resource not found from -32002 to -32602 (Invalid Params), aligning with the JSON-RPC specification. Includes the draft spec change.

@pja-ant pja-ant force-pushed the sep/resource-not-found-error branch from 5faa2ee to 348d8e7 Compare January 28, 2026 17:42
@pja-ant pja-ant force-pushed the sep/resource-not-found-error branch from 348d8e7 to 310784e Compare January 28, 2026 17:45
@pja-ant pja-ant changed the title SEP: Standardize resource not found error code (-32602) SEP-2164: Standardize resource not found error code (-32602) Jan 28, 2026
@pja-ant pja-ant marked this pull request as ready for review January 28, 2026 17:48
@pja-ant pja-ant requested a review from a team as a code owner January 28, 2026 17:48
@maxisbey

Copy link
Copy Markdown
Contributor

related: modelcontextprotocol/python-sdk#1821

@jonathanhefner

Copy link
Copy Markdown
Member

Previous discussion (for reference): #1545.

@pja-ant

pja-ant commented Jan 30, 2026

Copy link
Copy Markdown
Contributor Author

Previous discussion (for reference): #1545.

yeah I remember this, but didn't realize it was already so inconsistent. Any client has to handle various values anyway to work with real servers out there, so we might as well just trying and get all servers to converge.

@sep-automation-bot

Copy link
Copy Markdown

Maintainer Activity Check

Hi @pja-ant!

You're assigned to this SEP but there hasn't been any activity from you in 18 days.

Please provide an update on:

  • Current status of your review/work
  • Any blockers or concerns
  • Expected timeline for next steps

If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.


This is an automated message from the SEP lifecycle bot.

yarolegovich added a commit to modelcontextprotocol/go-sdk that referenced this pull request May 5, 2026
Change the error code returned by ResourceNotFoundError from -32002 to
-32602 (jsonrpc.CodeInvalidParams), aligning with
[SEP-2164](modelcontextprotocol/modelcontextprotocol#2164).

* Not gated with a protocol version check, because the previous error
code was never formally specified and the behaviour varied across SDKs.
* In case clients which rely on the old error code exist, the previous
behaviour can be restored with `MCPGODEBUG=customresnotfounderrcode=1`.
* `CodeResourceNotFound` deprecated since its only purpose going forward
is backward compatibility. The new code should use
`jsonrpc.CodeInvalidParams` directly.
* `CodeResourceNotFound` changed to `var` so it can stay in sync with
`ResourceNotFoundError` and existing code doing `code ==
mcp.CodeResourceNotFound` keeps working in both the default and compat
modes.
Resolve conflicts:
- docs/specification/draft/changelog.mdx: combine the resource-not-found
  error-code change with the deterministic-order, SEP-2243, and SEP-2549
  minor-change entries from main; renumber the error-code item to 6.
- docs/seps/index.mdx: regenerate from source (npm run generate:seps) so
  SEP-2164 lists alongside the SEPs that landed on main.

:house: Remote-Dev: homespace
@localden

Copy link
Copy Markdown
Contributor

/lgtm force

This was accepted by CM vote

@mcp-commander mcp-commander Bot added the accepted SEP accepted by core maintainers, but still requires final wording and reference implementation. label May 18, 2026
@mcp-commander mcp-commander Bot moved this from Draft to Accepted in SEP Review Pipeline May 18, 2026

@mcp-commander mcp-commander Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved on behalf of @localden via /lgtm force.

@mcp-commander mcp-commander Bot enabled auto-merge (squash) May 18, 2026 06:28
@mcp-commander mcp-commander Bot merged commit a7f4271 into main May 18, 2026
11 checks passed
@mcp-commander mcp-commander Bot deleted the sep/resource-not-found-error branch May 18, 2026 06:28
@localden localden removed the accepted SEP accepted by core maintainers, but still requires final wording and reference implementation. label Jun 4, 2026
koic added a commit to modelcontextprotocol/ruby-sdk that referenced this pull request Jun 14, 2026
…-2164

## Motivation and Context

SEP-2164 (modelcontextprotocol/modelcontextprotocol#2164, merged for the 2026-07-28 spec release)
standardizes the resource-not-found error on the JSON-RPC Invalid Params code (-32602),
dropping the legacy -32002 code, and both reference SDK implementations attach the requested URI
as structured error data (typescript-sdk#2267 throws `InvalidParams` with `data: { uri }`;
python-sdk#2344 adds a `ResourceNotFoundError` that maps to `code=-32602, data={"uri": ...}`).

The Ruby server already used -32602 (via `error_type: :invalid_params`) for its built-in not-found path
(`completion/complete` with an unknown `ref/resource` URI), but the response carried no structured data
and the generic "Invalid params" message, and there was no public error class for `resources_read_handler`
blocks to raise. The Ruby client never special-cased -32002, so nothing needed removal there.

- New public `MCP::Server::ResourceNotFoundError` (modeled on the `URLElicitationRequiredError` precedent):
  code -32602, message `"Resource not found: <uri>"`, and `data: { uri: <uri> }`.
  Custom `resources_read_handler` blocks raise it for unknown URIs; the README documents the pattern.
- The `completion/complete` `ref/resource` not-found path now raises this class,
  so its error response gains `data: { uri: }` and a descriptive message instead of
  the generic "Invalid params" text.
- The default `resources/read` behavior (returning empty contents for unknown URIs
  when no handler is registered) is intentionally unchanged; raising there would
  alter existing wire behavior.

Resolves #379.

## How Has This Been Tested?

New tests in `test/mcp/server_test.rb`:

- `resources/read` with a handler raising `ResourceNotFoundError` responds
  with code -32602, message `"Resource not found: file:///missing.txt"`,
  and `data: { uri: "file:///missing.txt" }`
- `completion/complete` with an unknown `ref/resource` URI carries the same code,
  message, and structured data

New test in `test/mcp/client_test.rb` asserts `Client#read_resource` surfaces
the -32602 code and the `data` hash unmodified through `Client::ServerError`
(regression: no special-casing swallows it).

The pre-existing completion error-code tests pass unchanged.
`bundle exec rake` (tests, RuboCop, and conformance baseline) passes.

## Breaking Changes

None at the JSON-RPC code level (-32602 before and after).
The `completion/complete` resource-not-found error response changes shape within
the error object: `message` becomes `"Resource not found: <uri>"` instead of
`"Invalid params"`, and `data` becomes `{ uri: <uri> }` instead of the message string.
Both members are advisory per JSON-RPC 2.0.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

final SEP finalized. SEP

Projects

Status: Accepted

Development

Successfully merging this pull request may close these issues.

8 participants