You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
OTel client span sets ERROR status for -32602 and other caller-error codes #3811
Since 2.3.0 (#3174) every JSON-RPC error response marks the client span ERROR with error.type set to the code. The OTel GenAI semantic conventions for MCP (docs/gen-ai/mcp.md, footnote on error.type) say the codes -32700, -32600, -32601, -32602 and -32002 "indicate that the caller sent a request the receiver could not serve and SHOULD NOT be considered errors"; only other codes should be. rpc.response.status_code should still carry the code.
The most common case is calling an unknown tool: the Go SDK server (and the TypeScript SDK) answer -32602, and the Python client span becomes ERROR with error.type=-32602.
Reproduction (Python 2.3.0 client against a Go SDK server):
git clone https://github.com/mkwitko/mcp-reliability && cd mcp-reliability
examples/python-sdk-streamable-http/run.sh
go run ./cmd/mcp-reliability doctor testdata/cross-python-client-go-server.jsonl
[WARN] MCP-ERR-005: span "tools/call missing" is marked failed (status=Error, error.type present=true) for a JSON-RPC code the semconv says SHOULD NOT be considered an error
Suggested change: in the dispatcher, when the error code is one of the five caller-error codes, set rpc.response.status_code but leave the span status Unset and skip error.type. The server side already has the equivalent classification. I can send a PR.
Implementing the shared-predicate design from @media-ctrl's analysis above, on both sites.
Root cause. Both OTel span sites mark every JSON-RPC error response as a failed span. The client site (src/mcp/shared/jsonrpc_dispatcher.py, inside the otel_span(...) wrapping the response wait) sets error.type=<code> plus StatusCode.ERROR for any ErrorData other than the SDK-only _CLOSED_OUTCOME sentinel. The server site (src/mcp/server/_otel.py) does the same for every MCPError, and for the ValidationError branch pinned to INVALID_PARAMS. OpenTelemetry semantic conventions treat caller/policy errors — the request was malformed, invalid, or unsatisfiable — as non-error outcomes, so -32700/-32600/-32601/-32602 and -32002 must not end a span with ERROR.
Approach. One shared predicate, is_caller_error(code) in src/mcp/shared/_otel.py, classifies the four standard codes (already constants in mcp-types/mcp_types/jsonrpc.py) plus -32002. -32002 is the retired resource-not-found code (reserved-never-reused, so mcp_types deliberately has no constant); it stays a documented literal in the predicate's set rather than adding a new public symbol. Both sites branch on the predicate: a caller error records only rpc.response.status_code (kept in both branches — the change touches status and error.type only), anything else keeps today's behaviour (error.type + StatusCode.ERROR + message). The ValidationError branch is pinned to INVALID_PARAMS, so it takes the caller path directly instead of branching on a condition that is always true.
On the error.type question raised above: a caller-error span now sets noerror.type at all, since a stringified wire code is a value no receiver can interpret against the semconv registry. Non-caller spans keep the existing stringified code untouched — moving it to a registry value is a separate change.
Branch (no PR from me: the org auto-closes PRs from contributors not assigned to the linked issue, and per CONTRIBUTING I won't ask for assignment): Shanmukh-l33t/python-sdk, branch fix/3811-otel-caller-error-status, based on current main (77001c96f9507be0f4d009b83210a384a5e08bda). Head: 480324860af528983c407d76304adb4e5977215e (fix), with the regression tests in 8adeeac08a3cb8cfcc55b43d5f629da4248a010b committed first.
Tests. Regression tests were written before the fix and fail on the unmodified parent with exactly the wrong span state (assert <StatusCode.ERROR: 2> == <StatusCode.UNSET: 0>, error.type set to the stringified code):
tests/shared/test_otel.py::test_caller_error_response_leaves_client_span_unset_without_error_type — client span for a -32602 response: status UNSET, no error.type, rpc.response.status_code kept.
tests/server/test_otel.py::test_method_not_found_leaves_server_span_unset_without_error_type — -32601 from an unregistered method.
tests/server/test_otel.py::test_validation_failure_leaves_server_span_unset_without_error_type — the ValidationError/INVALID_PARAMS path.
tests/shared/test_otel.py::test_is_caller_error_classifies_caller_codes_and_rejects_operation_failures — the predicate's classification.
Green after the fix: 23/23 across both OTel test files. The two tests that pinned the old contract now pin the non-caller path instead (test_client_span_records_error_status_when_peer_answers_with_internal_error, test_mcp_error_with_internal_code_marks_span_failed_with_error_type); that path also remains pinned by the untouched test_records_error_status_on_malformed_spec_result and test_records_error_status_on_handler_exception. Full suite: 6236 passed, 8 skipped, 1 xfailed; one failure, test_file_resources.py::test_permission_error, which only fails because my test box runs as uid 0 (root ignores the chmod 0o000) and is unrelated to this change. coverage run -m pytest -n 2 + coverage report: 100.00% including branch coverage, exit 0; strict-no-cover clean; ruff check/format and pyright clean on the changed files.
Deliberately untouched (a code-classification predicate can't decide these):
src/mcp/server/_otel.py's generic except Exception branch — records error.type as the exception qualname with an exception event;
the tools/callisError result branch — a tool-level failure that should stay StatusCode.ERROR regardless of JSON-RPC code.
AI-assisted change (Hermes Agent by Nous Research) — code, tests and this write-up.
Activity
media-ctrl commentedon Nov 4, 2026
fix(otel): do not mark client span ERROR for JSON-RPC caller-error co…
Shanmukh-l33t commentedon Nov 11, 2026
Implementing the shared-predicate design from @media-ctrl's analysis above, on both sites.
Root cause. Both OTel span sites mark every JSON-RPC error response as a failed span. The client site (
src/mcp/shared/jsonrpc_dispatcher.py, inside theotel_span(...)wrapping the response wait) setserror.type=<code>plusStatusCode.ERRORfor anyErrorDataother than the SDK-only_CLOSED_OUTCOMEsentinel. The server site (src/mcp/server/_otel.py) does the same for everyMCPError, and for theValidationErrorbranch pinned toINVALID_PARAMS. OpenTelemetry semantic conventions treat caller/policy errors — the request was malformed, invalid, or unsatisfiable — as non-error outcomes, so -32700/-32600/-32601/-32602 and -32002 must not end a span withERROR.Approach. One shared predicate,
is_caller_error(code)insrc/mcp/shared/_otel.py, classifies the four standard codes (already constants inmcp-types/mcp_types/jsonrpc.py) plus -32002. -32002 is the retired resource-not-found code (reserved-never-reused, somcp_typesdeliberately has no constant); it stays a documented literal in the predicate's set rather than adding a new public symbol. Both sites branch on the predicate: a caller error records onlyrpc.response.status_code(kept in both branches — the change touches status anderror.typeonly), anything else keeps today's behaviour (error.type+StatusCode.ERROR+ message). TheValidationErrorbranch is pinned toINVALID_PARAMS, so it takes the caller path directly instead of branching on a condition that is always true.On the
error.typequestion raised above: a caller-error span now sets noerror.typeat all, since a stringified wire code is a value no receiver can interpret against the semconv registry. Non-caller spans keep the existing stringified code untouched — moving it to a registry value is a separate change.Branch (no PR from me: the org auto-closes PRs from contributors not assigned to the linked issue, and per CONTRIBUTING I won't ask for assignment):
Shanmukh-l33t/python-sdk, branchfix/3811-otel-caller-error-status, based on currentmain(77001c96f9507be0f4d009b83210a384a5e08bda). Head:480324860af528983c407d76304adb4e5977215e(fix), with the regression tests in8adeeac08a3cb8cfcc55b43d5f629da4248a010bcommitted first.Tests. Regression tests were written before the fix and fail on the unmodified parent with exactly the wrong span state (
assert <StatusCode.ERROR: 2> == <StatusCode.UNSET: 0>,error.typeset to the stringified code):tests/shared/test_otel.py::test_caller_error_response_leaves_client_span_unset_without_error_type— client span for a -32602 response: status UNSET, noerror.type,rpc.response.status_codekept.tests/server/test_otel.py::test_method_not_found_leaves_server_span_unset_without_error_type— -32601 from an unregistered method.tests/server/test_otel.py::test_resource_not_found_code_leaves_server_span_unset_without_error_type— handler-raised -32002.tests/server/test_otel.py::test_validation_failure_leaves_server_span_unset_without_error_type— theValidationError/INVALID_PARAMSpath.tests/shared/test_otel.py::test_is_caller_error_classifies_caller_codes_and_rejects_operation_failures— the predicate's classification.Green after the fix: 23/23 across both OTel test files. The two tests that pinned the old contract now pin the non-caller path instead (
test_client_span_records_error_status_when_peer_answers_with_internal_error,test_mcp_error_with_internal_code_marks_span_failed_with_error_type); that path also remains pinned by the untouchedtest_records_error_status_on_malformed_spec_resultandtest_records_error_status_on_handler_exception. Full suite: 6236 passed, 8 skipped, 1 xfailed; one failure,test_file_resources.py::test_permission_error, which only fails because my test box runs as uid 0 (root ignores thechmod 0o000) and is unrelated to this change.coverage run -m pytest -n 2+coverage report: 100.00% including branch coverage, exit 0;strict-no-coverclean;ruff check/formatandpyrightclean on the changed files.Deliberately untouched (a code-classification predicate can't decide these):
src/mcp/server/_otel.py's genericexcept Exceptionbranch — recordserror.typeas the exception qualname with an exception event;tools/callisErrorresult branch — a tool-level failure that should stayStatusCode.ERRORregardless of JSON-RPC code.AI-assisted change (Hermes Agent by Nous Research) — code, tests and this write-up.