Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

MCP error contract — which channel carries which failure

Status: published decision table for issue #1613. Describes the server as it stands on top of commit ccdef614 plus the uncommitted working-tree changes that converted the last 16 reason-less rejection sites. Commit ccdef614 is the state after code slices 2–5 landed (EC-02 … EC-08) and closed EC-08's machine-readable half everywhere it was originally scoped; the working tree closes it everywhere else. This page states what the server does, not what it should do; a future change that invalidates a row must change this page in the same commit.

Evidence class: mixed, and the split is deliberate. Rows A1, A2, A3, A6, A7, A8, A9 and C1 are observed over a real transport — they are asserted on the wire in tests/mcp_error_channel_mapping_test.rs (A1, A2, A3), tests/mcp_ssrf_error_class_test.rs (A6–A9) and tests/mcp_validation_reason_code_test.rs (C1 and the data shape). Every other row is still statically derived: read out of the source, not exercised end-to-end. Rows A4, A5, A10–A19, B1–B8, C2–C4 and T1–T9 are in that second group. (A5 is the only SSRF row not covered end-to-end: no_host is unreachable from outside, which is exactly what its row says.)

Slug evidence is narrower than row evidence, and the two must not be conflated. The wire-level slug assertions cover exactly three validation slugs (unsupported_scheme, too_long, out_of_range in tests/mcp_validation_reason_code_test.rs) plus three SSRF slugs (forbidden_ip_literal, forbidden_ip_resolved, dns_resolution_failed in tests/mcp_ssrf_error_class_test.rs). The A4.x and A10–A14 slugs are not transport-observed: A4.x is pinned by the in-crate unit test path_gate::every_rejection_carries_field_and_reason_slug, which samples every branch of confine, and the A10–A14 slugs by construction — the reason-less constructor those sites used to call has been deleted, and no bare-string data producer remains anywhere in the crate (see the appendix). Nothing here is inferred from a hypothetical transport any more; see Unsettled rows for the one question that changed evidence class in the other direction and the one deliberate non-action.

Quick path for an agent consumer

HTTP status != 200                      → Channel 0. Transport refused the request. Fix the request shape.
JSON-RPC "error" member present         → Channel A. The call never ran. Fix the arguments.
result.isError == true                  → Channel B. The call ran and failed. The text is the reason.
result without isError                  → Channel C. The call ran. Read the body: it may be a
                                          diagnostic, a partial result, or a success.

Two things that table does not say, and that bite:

  • A malformed argument does not always reach Channel A. A deserialization rejection (rows A1, A2) arrives as isError: true — Channel B. Only a rejection raised by the handler body (row A3) is a JSON-RPC -32602. The type is the same on both routes; the wire shape is what differs. See A1–A3.
  • Channels A and B overlap textually. A isError: true body can contain the literal string -32602. Never discriminate on the code appearing in the text — see Channel overlap.

"Retriable" in this table means: repeating the identical call can succeed without the caller changing anything. Anything else is a caller change, not a retry.

The three channels (plus the one before them)

ChannelWire shapeHTTPCarriesCode
0 — transportbare status, usually no JSON-RPC body (T9 is the exception)401/406/408/413/415/422/429/500a request that never reached a toolnone (T9 adds a -32603 body)
A — protocol error{"error": {"code": …, "message": …, "data": …}}200the call was unroutable, or its arguments were refused by the handler body-32601 / -32602 / -32603
B — tool errorresult.isError = true200the tool ran and the job failed — or its arguments never deserializednone
C — success-shaped diagnosticresult, no isError200the tool ran; the body describes a non-success outcomenone

Channel A is the only channel with a machine-readable code and a machine-readable data.reason slug (see the reason taxonomy). Channel B carries no code: the only machine-readable signal is the boolean, and the reason is free text. Channel C has the same gap, which is the whole reason it is listed separately — see row C1.

Channel overlap — the text is not the discriminator

A Channel B body can literally contain -32602. Two independent facts combine:

  1. McpError::invalid_params(msg, data) builds an rmcp::ErrorData, and ErrorData's Display renders "{code}: {message}({data})" — the numeric code is part of the string form (rmcp-1.8.0/src/error.rs:8-16).
  2. On the deserialization route, rmcp wraps any serde error as "failed to deserialize parameters: {error}", so that rendered ErrorData — code and data included — is what lands in the isError: true body.

An A1/A2 rejection therefore reads, in the tool text, roughly failed to deserialize parameters: -32602: …({"field":"url","reason":"malformed"}) while carrying no error member at all. The only reliable discriminator is the wire shape: is there a top-level error member, or is result.isError true? Branch on that, never on a code appearing in the text.

This is also why the reason slug is the machine-readable half on this route: it is readable in the text (rmcp's Display appends the data JSON verbatim) even though it is not delivered as structured data. Parsing it out of prose is a last resort, not the contract — rows A1/A2 give no data a client can index.


Channel A — JSON-RPC protocol errors

Emitted when a tool function returns Err(McpError); McpHandler::call_tool (mcp_server/mod.rs:359-382) forwards that Err unchanged to rmcp.

Two things about this channel are not obvious from the table, and both were settled by issue #1613 rather than assumed:

  • It is not the channel every argument rejection takes. Only a rejection the handler body raises is Channel A — settled by observation in slice 3.
  • error.data is not a single shape. There are two live shapes, listed in the reason taxonomy: an object carrying both field and reason, and an object carrying reason alone. Every argument refusal carries a slug — the pre-EC-08 bare-string shape and the reason-less shape are both gone. The only Channel A rows still left with no data at all are the -32603 server faults (A15, A16), which never had a caller mistake to describe.

A1–A3 · argument deserialization (before the handler body)

#ConditionCodeRetriableAgent shouldSource
A1URL argument is not http(s), is oversize, or carries embedded credentialsnone — result.isError = true, no error member (observed)NoReshape the URL. Never retry unchanged.mcp_server/params.rs:81-99 (McpUrl::try_from); observed in tests/mcp_error_channel_mapping_test.rs:99-127
A2Unknown JSON key in the argument object (deny_unknown_fields)none — result.isError = true, no error member (observed)NoDrop the unknown key.mcp_server/params.rs:7 (per-struct attribute, first at :316); observed in tests/mcp_error_channel_mapping_test.rs:139-166
A3In-handler params.validate()? semantic rejection-32602 (observed)NoFix the named field; data.field names it.every validate() in mcp_server/params.rs (e.g. 461-475); observed in tests/mcp_error_channel_mapping_test.rs:196-217

A1 and A3 produce the same Rust error type (McpError::invalid_params is rmcp::ErrorData) but travel different routes and land on different channels: A1 is raised inside rmcp's Parameters<P> deserialization and arrives as result.isError = true; A3 is returned from the tool function and arrives as error.code = -32602 with no result member. That was the open question under Unsettled rows; it is now settled by test, and the answer is that they do not reach the client as the same code.

The mechanism is worth knowing, because it is why McpUrl::try_from does not have to fake anything. rmcp 1.8.0's Parameters<P> extractor wraps any serde error with its own "failed to deserialize parameters: " prefix (rmcp-1.8.0/src/handler/server/tool.rs:181-196), and into_tool_argument_error downgrades to isError: true only when the code is INVALID_PARAMS and that prefix is present (rmcp-1.8.0/src/handler/server/router/tool.rs:144-156). A handler-raised rejection never carries the prefix, so it is never downgraded. One shared Rust type, two routes, two channels.

A3 covers every branch below. They share one constructor (validation::invalid_params_with_reason), so they share one channel, one code, and one data shape — the split is by condition, not by envelope.

#A3 sub-conditionFielddata.reasonRetriableAgent shouldSource
A3.1URL empty, > 8192 B, unparseable, or non-http(s) schemeurl / variesempty / too_long / malformed / unsupported_schemeNoResend a valid absolute http(s) URL.mcp_server/validation.rs:137-174
A3.2Path empty, > 1024 B, absolute, drive-lettered, ..-bearing, or a rejected path componentvariesempty / too_long / path_not_allowedNoSend a relative, traversal-free path.mcp_server/validation.rs:176-237, 333-374
A3.3HTML / markdown / content blob > 1 MiBvariestoo_longNoChunk the input.mcp_server/validation.rs:41, 376-393
A3.4max_pages outside 1..=100 000, max_depth outside 0..=10max_pages / max_depthout_of_rangeNoClamp to the advertised cap.mcp_server/params.rs:152-183
A3.5urls empty or over cap, concurrency out of rangeurls / concurrencyempty / out_of_rangeNoFix the batch.mcp_server/params.rs:461-485, mcp_server/validation.rs:555-618
A3.6js_strategy not a known strategyjs_strategynot_in_allowed_setNoUse static / hybrid / full.mcp_server/params.rs:526-532
A3.7checkpoint_dir present but blankcheckpoint_diremptyNoOmit it or name a real directory.mcp_server/params.rs:533-540
A3.8Enum-ish string not in the allowed setvariesnot_in_allowed_setNoUse a listed value; the message enumerates them.mcp_server/validation.rs:751-762
A3.9Filename not a single safe component (traversal, separator, reserved name, Windows-invalid char)filenameempty / too_long / path_not_allowedNoSend one flat component.mcp_server/validation.rs:620-733, 287-331

Since slice 5, error.data on every row above is the structured object {"field": "<field>", "reason": "<slug>"}. Before that it was a bare JSON string holding only the field tag, so a client could tell which field was wrong but never why, and had to parse prose. The field survived the restructure — it is now data.field — and data.reason is the new machine-readable half. Both are contract: see the reason taxonomy.

A4 · path confinement (root-of-trust)

#ConditionCodedata.reasonRetriableAgent shouldSource
A4.1Empty path-32602emptyNoName a directory.mcp_server/path_gate.rs:281-286 via mcp_server/state.rs:332, 352
A4.2Path over MAX_PATH_LEN (1024 B)-32602too_longNoShorten the path.mcp_server/path_gate.rs:288-293
A4.3Rooted-but-not-absolute form (C:foo, \foo)-32602path_not_allowedNoUse a genuinely absolute or genuinely relative path.mcp_server/path_gate.rs:296-303
A4.4.. traversal component-32602path_not_allowedNoSend a traversal-free path.mcp_server/path_gate.rs:308-313
A4.5Absolute path with no export roots configured-32602path_not_allowedNoUse a relative path, or tell the operator to set --export-roots.mcp_server/path_gate.rs:321-334 via mcp_server/state.rs:332, 352
A4.6Absolute path outside every configured export root-32602path_not_allowedNoRe-target under a configured root.mcp_server/path_gate.rs:340-348

The gate is fail-closed: with zero roots configured, every absolute path is refused (mcp_server/path_gate.rs:321). Relative paths are allowed and resolve against the server's CWD (mcp_server/path_gate.rs:315-319).

All six branches now emit the full {"field": "output_dir" | "checkpoint_dir", "reason": <slug>} envelope — there is no reason-less shape left. Only A4.1 and A4.2 differ from the shared path_not_allowed: their remedy is fill it in and shorten it, not use a different path, and a slug that sends the agent down the wrong remedy is worse than no slug at all. The four path_not_allowed branches are deliberately not split further — "use a safe path inside an allowed root" is one instruction for all of them, and the message carries which rule fired. Only the data payload moved: the gate's control flow, messages, -32602 code and allow/deny decisions are byte-for-byte unchanged.

A5–A9 · SSRF entry pre-check

All five branches come from one function, validate_url_no_ssrf (mcp_server/ssrf.rs:96-187). Since slice 2 they are separated into three classes, and the split is expressed twice: in the JSON-RPC code, and in a data.reason slug.

#ConditionClassCodedata.reasonRetriableAgent shouldSource
A5URL has no hostcaller input-32602no_hostNoUnreachable in practice — McpUrl always carries a host.mcp_server/ssrf.rs:118-123
A6Literal IP is in a forbidden range (loopback / private / link-local / CGNAT / ULA)policy-32602forbidden_ip_literalNoStop. Retargeting is the only fix.mcp_server/ssrf.rs:130-142
A7DNS resolver returned an errorinfrastructure-32603dns_resolution_failedYesRetry — the argument is fine, the server's resolver is not.mcp_server/ssrf.rs:148-159
A8DNS returned an empty answer setinfrastructure-32603dns_no_addressesYesRetry — same class as A7.mcp_server/ssrf.rs:161-170
A9A resolved address is in a forbidden rangepolicy-32602forbidden_ip_resolvedNoStop. This is a policy refusal, not a transient.mcp_server/ssrf.rs:172-185

A7 and A8 changed class in slice 2. They used to be -32602 with data: None, identical to a caller aiming at internal infrastructure — the only way to tell a transient DNS outage from an SSRF attempt was to parse Spanish message text. They are now -32603 internal_error: the argument is correct and the server's resolver is not, which is the same fault class this crate already reports that way (rows A15, A16). Retriability follows the code: the two DNS rows are the only retriable rows in Channel A.

Policy and caller input still share -32602 on purpose — the knob-matrix suite pins the loopback refusal at exactly that code, and the SSRF knob documentation advertises the shape, so changing it would break pinned probes for no gain. That is why data.reason is load-bearing here and not decoration: the slug, not the code, is what separates the classes. The five SSRF slugs are a separate, closed set from the seven validation slugs, and they carry no field (an SSRF refusal is not a bad field); see the reason taxonomy.

This pre-check is not the enforcement point. Every scrape client is independently guarded at connect time by webfang_core::domain::ssrf_guard (literal-IP redirect policy + validating resolver), so A6/A9 are fast-fail UX and defense in depth. See docs/ssrf-layers.md for the full layer matrix.

A10–A17 · handler-local protocol errors

#ConditionCodedata.reasonRetriableAgent shouldSource
A10content_format / pipeline_format not a known export format-32602not_in_allowed_setNoUse jsonl / vector / auto.mcp_server/handlers/export.rs:196-202, 409-415
A11filename rejected by the sanitizer, or unparseable inside the synthetic export URL-32602path_not_allowedNoSend one flat component.mcp_server/handlers/export.rs:209-215, 234-240, 324-331, 362-369, 469-475
A12Synthetic export URL for the filename fails the hardened URL gate-32602malformedNoReshape the filename.mcp_server/handlers/export.rs:244-257
A13js_strategy failed to parse in the handler (post-validate path)-32602not_in_allowed_setNoUse a known strategy.mcp_server/handlers/scraping.rs:457-463
A14Explicit sitemap_url fails the hardened URL re-wrap-32602unsupported_schemeNoReshape the sitemap URL.mcp_server/handlers/scraping.rs:599-610
A15Per-category semaphore closed or poisoned-32603none — data is nullNoReport it; the server is unhealthy.mcp_server/macros.rs:16
A16Record conversion failed: DocumentChunk::validate() or metadata serialization-32603none — data is nullNoReport it; the payload was not produced.mcp_server/handlers/scraping.rs:106, 109, 212, 215, 1121, 1127
A17SSRF pre-check failure on the axtree tool (re-raised unchanged)as A5–A9as A5–A9as A5–A9As A5–A9 — read data.reason, the code is the SSRF channel's.mcp_server/handlers/axtree.rs:66-74

A15, A16 and the two SSRF DNS branches (A7, A8) are the only -32603 values this crate constructs for a tool call. They are server faults, not caller mistakes, and must not be retried — which is also why they are the only Channel A rows with no data at all: there is nothing for the caller to branch on. A17 is a forwarding site, not a construction: it re-raises whatever validate_url_no_ssrf produced, so its code and slug are inherited.

Two slug choices in this table are not mechanical, and both are deliberate. A12 reports malformed, not unsupported_scheme: the scheme there is server-built (https://webfang.local/<filename>), so unsupported_scheme would describe a URL the caller never sent and hand it unusable advice; try_from_url also collapses "unparseable" and "not http(s)" into one error, exactly as the McpUrl boundary does. A14 is the mirror image and reports unsupported_scheme: there the value was already parsed by McpUrl, so the scheme allow-list is the only reachable cause and the precise slug is the true one.

A18–A19 · produced by rmcp, not by this crate

#ConditionCodeRetriableAgent shouldSource
A18Unknown JSON-RPC method (e.g. a tool name that is not registered)-32601NoCall a name from tools/list.rmcp; not constructed here — mcp_server/server.rs:166-177, pinned by tests/mcp_transport_contract_test.rs:138
A19A panic escapes the HTTP request path-32603 body, HTTP 500NoReport it. The body echoes the JSON-RPC id the client sent whenever one can be recovered (see the rules below). The tool-level panic path (B1) is the one that keeps the session alive.mcp_server/panic_containment.rs (jsonrpc_internal_error_response), outermost backstop in mcp_server/server.rs (jsonrpc_panic_response)

Which id a contained panic echoes

The -32603 body always carries an id, and what it carries is a stated rule, not a best effort. Both containment layers share one response builder, so the shape never depends on which layer caught the panic.

id echoedwhenrule id
the parsed id memberPOST body is an object with an id memberenvelope
nullthe object closed with no id member (a JSON-RPC notification)notification
nullthe object sent "id": null explicitlynull_id
nullthe body is a top-level array (a JSON-RPC batch)batch
nullnon-JSON, empty, a bare scalar, a non-POST request, or an unreadable bodynot_a_request
nullthe envelope did not close inside the 64 KiB scan windowscan_window

A null id is recorded on the jsonrpc.id_source span field (mcp_jsonrpc_panic_containment), so "the client sent a batch" is distinguishable from "the body was garbage" in the trace. null never means the mapping failed: the code is -32603 either way. Source of truth: crates/webfang_mcp/src/mcp_server/panic_containment.rs.


The reason-slug taxonomy — the machine-readable contract

data.reason is the half of this contract an agent branches on. Before slice 5, Channel A told a caller which field was wrong and nothing about why, so every consumer parsed prose. Since EC-08 the data member is an object and reason is one of a closed set of stable slugs, declared as a contract in mcp_server/validation.rs:64-99. There is deliberately no reason-less constructor left in the crate: the invalid_params(field, msg) escape hatch that path_gate.rs and the handler-inline sites used to call was deleted once nothing called it any more, and a caller that cannot name a slug must now pick the closest one (mcp_server/validation.rs:101-104). That is what makes the taxonomy exhaustive — a consumer branching on data.reason can rely on it being there.

The seven validation slugs

SlugMeansWhat the caller should do
emptya required value is emptyfill it in
too_longthe value exceeds a byte capshorten it
malformedpresent but unparseablefix its shape
unsupported_schemethe URL scheme is not http/httpsuse http or https
path_not_allowedany structural path rejection — the filename rules (absolute, UNC prefix, drive letter, .., non-flat filename, Windows reserved name, Windows-invalid character, trailing ./space) and the export-root confinement rules in path_gate.rs (rooted-not-absolute, .., absolute with no roots, absolute outside every root)use a safe relative path and a plain filename
out_of_rangea numeric value is outside its inclusive boundsclamp it
not_in_allowed_setan enum-ish value is not in the allowed listpick a listed value

Coarse is deliberate, and the set is load-bearing. A slug's job is to tell the agent what to do, not to restate the message; seven stable values beat forty brittle ones. Downstream tooling branches on these strings, so do not rename one, add an eighth, or remap a condition to a different slug without changing this page in the same change. path_not_allowed deliberately collapses those twelve rules into one slug, because their remedy is one instruction — use a safe path — and the message carries the specifics.

The SSRF slugs

A separate, disjoint set — the SSRF pre-check classifies a target, not a request field, so it carries no field at all:

SlugClassCode
no_hostcaller input-32602
forbidden_ip_literalpolicy-32602
forbidden_ip_resolvedpolicy-32602
dns_resolution_failedinfrastructure-32603
dns_no_addressesinfrastructure-32603

The data shapes a client must tolerate

ShapeEmitted byReader
{"field": "<field>", "reason": "<slug>"}every field-bearing rejection: the 44-branch validation.rs funnel, the six inline bounds in params.rs (A1, A3.x), the six path_gate.rs branches (A4.x), and the ten handler-inline sites in handlers/export.rs / handlers/scraping.rs (A10–A14)index field and reason
{"reason": "<slug>"} — no fieldssrf.rs, 3 branches (A5, A6, A9)index reason; field is legitimately absent

That is the whole of what the server produces. A client may still meet a bare string or a data with no reason in the wild, because error.data is sender-defined and validation::reason_of deliberately tolerates all three cases (data absent, a non-object, or an object with no reason key) rather than panicking (mcp_server/validation.rs:122-124, pinned by reason_of_tolerates_a_missing_or_foreign_data_payload). Keep that tolerance in the reader; do not document either as a shape this server can emit.

validate_url's parallel channel

The one success-shaped diagnostic that reports a rejection reuses the same slug under a different key, because it is not a JSON-RPC error and has no data: the body is {"valid": false, "reason": <message only>, "reason_code": <slug>} (row C1). reason is now the message alone; it used to be ErrorData::to_string(), which leaked the numeric code and a raw data blob into a human-facing field. reason_code carries the slug, so one taxonomy covers both channels. The valid: true field set is unchanged.


Message language — the ratified (inconsistent) contract

The repo-wide rule is "user-facing errors in Spanish, internal logs in English". The MCP error channels do not follow it uniformly, and that is now a documented state rather than an accident to be papered over.

ChannelLanguage as it actually is
A — structural / validationEnglish in validation.rs (every require_* message) and in path_gate.rs; Spanish in one deliberate island, validation::filename_component_error (mcp_server/validation.rs:291-323 — all six of its messages), and also in ssrf.rs, handlers/export.rs, and the js_strategy / checkpoint_dir / sitemap_url messages in params.rs and handlers/scraping.rs
B — operationalSpanish by intent, with a few English literals surviving: "no valid URLs provided" (mcp_server/handlers/scraping.rs:264) and the three "HTTP error: …" messages (mcp_server/handlers/scraping.rs:780-783, 852, 1019). Messages that forward an upstream Error::to_string() are language-dependent on their source.
C — success-shapedmixed: "no vault detected" and "not an SPA - sufficient content found" are English, and validate_url's failure reason is whatever require_http_url produced — also English.

Unifying this was deliberately not done in issue #1613. The reason is that it would buy nothing for a programmatic consumer: data.reason makes the branch language-free, and the message text is explicitly not part of the contract. Rewriting the message strings behind these rows would churn the diff of a contract change, put the language split in the path of existing message-matching probes, and change nothing a client can rely on. (How many strings that is was deliberately not counted: an exact figure would be a snapshot, and this page is about a contract, not a census.)

This is a deviation from the repo-wide convention, recorded here so a maintainer can revisit it. The honest framing: the convention says these strings are user-facing, and they are read by an autonomous agent rather than a person, so "user-facing" is arguably the wrong lens — but that is an argument, not a decision, and the decision belongs to the maintainer. If it is revisited, the taxonomy section is the anchor: only the slugs are frozen, so translating a message is a compatible change while renaming a slug is not.


Channel B — isError: true tool results

Every row here is built by provenance::neutralized_error (mcp_server/provenance.rs:275-294) or by the honest_error wrappers (mcp_server/handlers/ai.rs:38-42, mcp_server/handlers/axtree.rs:25-28). Text is neutralized (ANSI + C0/DEL stripped, fence sentinels escaped) and capped, but no provenance envelope and no code is added — the reason is the text and nothing else.

Slice 4 moved four conditions into this channel from Channel C: three serialization-failure classes that used to return a placeholder body as a success (now B8.1–B8.3) and the inverted Obsidian severity (now B7.3). The rule they restore is the one render_metrics already followed: if the tool could not produce the answer it promised, the answer is isError: true — never a success whose body happens to read like a failure.

B1 · contained panic

#ConditionCodeRetriableAgent shouldSource
B1A tool body panicked; the panic was caught at the dispatch boundarynoneYes, with a caveatRetry, but know that containment restores the transport, not the side effects — a tool that panicked after writing an export or charging a rate-limit token will duplicate that work.mcp_server/mod.rs:359-380 (containment + rationale), client text at mcp_server/mod.rs:268-270

B2 · site policy denial (robots.txt / WAF)

#ConditionCodeRetriableAgent shouldSource
B2.1robots.txt rules forbid the URLnoneNoStop, or retry with the tool's own opt-out (ignore_robots) if the caller has permission.mcp_server/handlers/scraping.rs:1154-1171 (robots_denied_response), used by mcp_server/handlers/scraping.rs:759-771 (discover_urls), mcp_server/handlers/scraping.rs:957-970 (detect_spa), and the inline gate at mcp_server/handlers/scraping.rs:74-84; mcp_server/handlers/ai.rs:122-124
B2.2The policy guard refused (guard condition, not a rules denial)noneNoTreat as a policy refusal.mcp_server/state.rs:375-390
B2.3Live scrape inside the export pipeline deniednoneNoAs B2.1; the message is prefixed with the target URL.mcp_server/handlers/export.rs:428-435

B3 · scrape / crawl operational failure

#ConditionCodeRetriableAgent shouldSource
B3.1scrape_url — fetch, Readability extraction, or content sink failednoneDepends on the class in the textRead the text; a transient network fault and a hard WAF block look the same here.mcp_server/handlers/scraping.rs:121-130
B3.2scrape_with_options — samenoneSameSame.mcp_server/handlers/scraping.rs:227-236
B3.3scrape_batch — whole-batch failurenoneYes if transientRetry the batch; per-URL failures inside a successful batch are rows, not errors (C3).mcp_server/handlers/scraping.rs:380-398
B3.4crawl_site — engine run failednoneYes if transientRetry the crawl.mcp_server/handlers/scraping.rs:534-544
B3.5crawl_with_sitemap — discovery failednoneYes if transientRetry.mcp_server/handlers/scraping.rs:713-731
B3.6crawl_with_sitemap — sitemap session run failednoneYes if transientRetry.mcp_server/handlers/scraping.rs:694-711
B3.7discover_urls / discover_sitemap — link extraction or sitemap read failednoneYes if transientRetry.mcp_server/handlers/scraping.rs:830-840, mcp_server/handlers/scraping.rs:915-925
B3.8download_assets — asset fetch or write failednoneYes if transientRetry; already-downloaded assets are content-addressed.mcp_server/handlers/assets.rs:88
B3.9extract_links — base-URL resolution failednoneNoFix the input HTML or base URL.mcp_server/handlers/content.rs:87
B3.10url_to_file_path — OutputPath::from_url failednoneNoFix the URL.mcp_server/handlers/url_utils.rs:210
B3.11crawl_site / crawl_with_sitemap — the run's extracted records exceed the session result budget (64 MiB default), so nothing was retained for export (#1611, F7)noneYes, with a smaller runRe-run with fewer max_pages, or crawl per section. The text names the budget, the measured size, and how many records were kept vs dropped.mcp_server/handlers/scraping.rs (within_session_budget, session_budget_message, store_session_results)

The per-class retry policy these texts inherit is docs/error-classification-matrix.md. The MCP channel carries no exit code, so the class is not machine-readable here — the agent must parse the text.

B4 · direct-fetch HTTP failures

#ConditionCodeRetriableAgent shouldSource
B4.1discover_urls — non-2xx status (a real failure, deliberately not an empty link set)none4xx no / 5xx yesRead the status in the text.mcp_server/handlers/scraping.rs:776-791
B4.2discover_urls — transport failurenoneYesRetry.mcp_server/handlers/scraping.rs:844-853
B4.3detect_spa — transport failurenoneYesRetry.mcp_server/handlers/scraping.rs:1010-1020
B4.4semantic_cleaner — page fetch failednoneYes if transientRetry.mcp_server/handlers/ai.rs:134-143
B4.5get_accessibility_snapshot — snapshot fetch failed (both formats)noneYes if transientRetry.mcp_server/handlers/axtree.rs:136-147, 168-180

B5 · export failures

#ConditionCodeRetriableAgent shouldSource
B5.1No session results to export (no crawl ran, or its extraction produced nothing)noneNoRun a crawl first. This is a precondition, not a fault.mcp_server/handlers/export.rs:115-121
B5.2Blocking-pool join for the session snapshot failednoneYesRetry.mcp_server/handlers/export.rs:136-142
B5.3export_file with empty / whitespace-only contentnoneNoSend real content.mcp_server/handlers/export.rs:186-190
B5.4export_file — document chunk validation failednoneNoFix the content.mcp_server/handlers/export.rs:269-275
B5.5Exporter construction failednoneDependsRead the text.mcp_server/handlers/export.rs:278-284
B5.6Export write failed (all four export tools)noneDependsRead the text.mcp_server/handlers/export.rs:57-61, 294-298
B5.7process_export_pipeline — live scrape failednoneDependsRead the text; it names the URL.mcp_server/handlers/export.rs:444-449

B6 · feature gating and missing ports

#ConditionCodeRetriableAgent shouldSource
B6.1AI tool called with no embeddings provider configurednoneNoConfigure a remote embeddings provider (--embedding-provider <id> or WEBFANG_EMBEDDING_PROVIDER); there is no local model and no flag that turns one on.mcp_server/handlers/ai.rs:58-64 (ai_unavailable), used at mcp_server/handlers/ai.rs:137, mcp_server/handlers/ai.rs:206-208, mcp_server/handlers/ai.rs:216
B6.2AI not compiled into the binary retired (ADR-0004 paso 6: the ai feature is gone; the AI tools are always compiled in and resolve their EmbeddingPort remotely via --embedding-provider)noneNonone — rebuild advice no longer applies; see ai-onnx-migration.md.same helper, mcp_server/handlers/ai.rs (line numbers may move)
B6.3Vault note repository not configurednoneNoOperator must configure persistence.mcp_server/handlers/ai.rs:201-204
B6.4chromium not compiled (axtree tool)noneNoRebuild with --features chromium.mcp_server/handlers/axtree.rs:185-197
B6.5Semantic cleaner / inference / embedding failednoneNoReport it; this is a server-side AI fault.mcp_server/handlers/ai.rs:144-147, 270
B6.6Response serialization failed (AI + axtree)noneNoReport it; the payload could not be built.mcp_server/handlers/ai.rs:161-168, 263-268; mcp_server/handlers/axtree.rs:121-133

B7 · local integration failures

#ConditionCodeRetriableAgent shouldSource
B7.1build_obsidian_uri / open_in_obsidian — vault name or file path rejectednoneNoFix the vault name or note path.mcp_server/handlers/obsidian.rs:72-77, 99-104
B7.2open_in_obsidian — the dispatch command could not be started at all (Err)noneYesRetry; Obsidian may not be installed.mcp_server/handlers/obsidian.rs:137
B7.3open_in_obsidian — the URI handler reported DispatchStatus::HandlerFailed (the OS handler exited non-zero)noneYesRetry after installing/registering the handler. Moved here from Channel C in slice 4: the requested action did not happen, so it is a tool error. The ⚠️ marker that used to fake the severity inside a success body is gone — the envelope carries it now.mcp_server/handlers/obsidian.rs:134-136 (in dispatch_outcome_to_result, mcp_server/handlers/obsidian.rs:126-139)
B7.4get_scrape_metrics — no scrape has been recorded in this processnoneNoRun a scrape first. Precondition, not a fault.mcp_server/handlers/security.rs:204-208
B7.5get_scrape_metrics — snapshot serialization failednoneNoReport it. This is the render_metrics precedent the four B8 sites now follow.mcp_server/handlers/security.rs:209-213
B7.6scrape_batch — every input URL was rejected before the runnoneNoFix the URLs.mcp_server/handlers/scraping.rs:263-265

B8 · reply serialization failed (server-side)

Added in slice 4. Each of these four sites used to do to_string_pretty(..).unwrap_or_else(|_| "failed to serialize") and return that literal as a successful result — a lost report that was indistinguishable from a real one, which is the single shape an agent cannot detect. They are ordinary Channel B rows now.

#ConditionCodeRetriableAgent shouldSource
B8.1download_assets — the asset list could not be serializednoneNoReport it; the download report was lost. Do not treat any body as authoritative.mcp_server/handlers/assets.rs:113-125 (assets_tool_result)
B8.2extract_links — the link list could not be serializednoneNoReport it; the link list was lost.mcp_server/handlers/content.rs:234-246 (links_tool_result)
B8.3discover_urls / discover_sitemap — the URL list could not be serializednoneNoReport it; the link list was lost.mcp_server/handlers/scraping.rs:1239-1256 (discovered_urls_tool_result)

The old placeholder body cannot be produced any more — a client no longer needs to special-case the literal string "failed to serialize". These rows are not -32603: the enclosing match already returns a CallToolResult directly, and ?-propagating would have split one function's failures across two channels. Retrying will not help; the payload types' Serialize impls are total, so these branches are defensive.


Channel C — success-shaped diagnostics

A result with no isError and no error member. The call succeeded; the body describes something that is not a plain success. This is the channel an agent cannot distinguish from a real success by shape alone — that is why it is enumerated rather than folded into B.

Slice 4 shrank this channel from six conditions to the four below, and the IDs were renumbered: the old C2 (the Obsidian severity inversion) became B7.3, and the old C3 (the "failed to serialize" placeholder) was eliminated outright — its four sites are now B8.1–B8.3. Old C4/C5/C6 are therefore new C2/C3/C4. What remains here is a deliberate diagnostic, not a leak: every row below is a tool that succeeded at the only thing it actually does, and reports a negative finding in the body.

| # | Condition | Code | Retriable | Agent should | Source | | :-: | :--- | :-: | :-: | :-: | :-: | :-: | | C1 | validate_url reports an unusable URL as {"valid": false, "reason": …, "reason_code": …} | none | No | Parse the JSON and branch on valid — never on isError. This is the only tool whose failure is a success by design (issue #590, bug #7). Since slice 5 its reason is the message alone and the slug moved to its own reason_code field; the tool's description now states the success-shaped contract outright. | mcp_server/handlers/url_utils.rs:73-82; success twin at mcp_server/handlers/url_utils.rs:58-71 | | C2 | A run completed with per-item failures (failed_url records; errors / error_breakdown fields) | none | Per item | Read the per-item records; the run itself is a success. | mcp_server/handlers/scraping.rs:1129-1142 (failure records), returned through mcp_server/handlers/scraping.rs:372-379; crawl summary at mcp_server/handlers/scraping.rs:519-534 | | C3 | detect_obsidian_vault found no vault ("no vault detected") | none | No | A negative result, not a failure. | mcp_server/handlers/obsidian.rs:53-55 | | C4 | detect_spa found sufficient content ("not an SPA - sufficient content found") | none | No | A negative result, not a failure. | mcp_server/handlers/scraping.rs:1005-1007 |

The old C3 row is gone for good. It promised that a body equal to the literal "failed to serialize" meant a lost report. Slice 4 removed the four sites that could produce it, so no tool can emit that body any more. A client still special-casing the string is guarding against something the server no longer does — the equivalent failure now arrives as an ordinary isError: true result (B8.1–B8.3).


Channel 0 — transport refusals (no JSON-RPC exists yet)

These never reach a tool. The client sees an HTTP status and, in most cases, no JSON-RPC body at all. Every row here is statically derived — these statuses are produced by middleware, not by a tool, and no test in this crate observes them over a live listener.

#ConditionStatusRetriableAgent shouldSource
T1Missing / malformed / wrong bearer token, and the server's own fail-closed default: no token configured and anonymous operation not explicitly enabled (#1611, G-18)401NoFix the Authorization header — or, if the server was started without a token, know that the operator must set one (--auth-token / WEBFANG_MCP_AUTH_TOKEN) or opt in to --allow-anonymous on loopback. A 401 with no token configured is a SERVER configuration state, not a wrong guess: the binary refuses to start in that state unless the opt-in is present.mcp_server/auth.rs, require_auth_or_explicit_anonymous in mcp_server/server.rs
T2Rate-limit quota exceeded429 + Retry-AfterYes, after backoffSlow down for the advertised number of seconds. The quota is per credential (keyed), so another caller's traffic does not consume yours.mcp_server/server.rs (rate_limit_middleware, rate_key)
T3Session-admission cap exceeded429Yes, after the windowSlow down. Bounded by --max-sessions / --session-cap-window-secs.mcp_server/server.rs:629-677
T4Request took longer than --request-timeout-secs408YesRetry. Note what it bounds: the request FUTURE, not a streaming body — once an SSE stream is answering, events keep flowing past this deadline (the accepted residual half of #1611 G-20; the "SSE channels uncapped" half no longer holds on rmcp 1.8.0, whose session/event channels are built at SessionConfig::channel_capacity = 16).mcp_server/server.rs (TimeoutLayer)
T5Body over --body-limit-bytes413NoShrink the payload.mcp_server/server.rs:225
T6Accept missing both application/json and text/event-stream406NoFix the request headers.rmcp StreamableHttpService; matrix at mcp_server/server.rs:166-173
T7Content-Type not application/json, or the body is not JSON-RPC 2.0415NoFix the request.rmcp; same matrix
T8Non-initialize request with no mcp-session-id422NoComplete the handshake first.rmcp; same matrix
T9Panic on the HTTP request path500 + JSON-RPC -32603 bodyNoReport it. The body echoes the JSON-RPC id when one is recoverable; see the id rules above.mcp_server/panic_containment.rs

Layer order matters for reading this, and #1611 F5 changed it. Outermost to innermost: panic backstop → tracing → body limit → timeout → auth → rate limit → session cap → id-echoing panic containment → the rmcp service. Two properties follow, and each is pinned by a test rather than by a comment:

  • A request refused 401 (no or wrong token) never reaches the rate limiter, so an unauthenticated flood cannot spend the authenticated caller's quota and lock the operator out of its own server.
  • A request refused 401 or shed 429 never consumes a session slot, so the session cap measures sessions rather than rejections.

Unsettled rows

EC-02 — SETTLED by test, not by reasoning. The question was whether A1/A2 (raised inside rmcp's argument deserialization) and A3 (raised by the handler body) reach the client as the same JSON-RPC code, given that they share one Rust error type (McpError::invalid_params is rmcp::ErrorData). They do not, and crates/webfang_mcp/tests/mcp_error_channel_mapping_test.rs now records both error.code and result.isError for all three routes against a live server:

RouteObservedTest
McpUrl deserialization (scrape_url with file:///etc/passwd)result.isError = true, no error membermcp_error_channel_mapping_test.rs:99-127
unknown field (scrape_with_options with typo_field)result.isError = true, no error membermcp_error_channel_mapping_test.rs:139-166
handler params.validate()? (crawl_site with max_depth: 11)error.code = -32602, no result membermcp_error_channel_mapping_test.rs:196-217

The mechanism is rmcp's own message prefix, described in A1–A3. No production code changed to settle it. The older hedged helper tests/params_rejection_test.rs::assert_url_argument_rejected, which "accepts EITHER rejection shape", is now strictly weaker than the new suite and is kept only because it also asserts the reason text; it is no longer the evidence for these rows.

Rows the code slices changed — all landed:

FindingRow affectedSliceStatus
EC-02 — the rmcp argument-rejection mappingA1, A2, A33Landed — settled by test, rows rewritten above
EC-03 — SSRF policy and DNS failures shared invalid_paramsA7, A82Landed — -32603 + data.reason; classes separated
EC-04 — the third channel was undocumentedC15Landed — reason_code slug + an explicit success-shaped description
EC-06 — a serialization failure returned success with a placeholderwas C34Landed — C3 deleted; the four sites are now B8.1–B8.3
EC-07 — DispatchStatus::HandlerFailed was returned as tool successwas C24Landed — moved to B7.3, ⚠️ marker dropped
EC-08 — validation text was English while operational errors were Spanish; no machine-readable reasonA3.x, A4.x, A10–A14, B*, C15Landed on the machine-readable half — data.reason is now present on every argument refusal the server raises (the -32603 server faults, A15/A16, carry no data and never did). The 16 sites slice 5 left behind (6 in path_gate.rs, 10 handler-inline in handlers/export.rs / handlers/scraping.rs) were converted, and the reason-less constructor they called was deleted, so both shapes that survived slice 5 are gone; see A4, A10–A17 and the shape table. The language half was deliberately not done, and remains open: see Message language.

EC-05 — a deliberate, justified non-action, not an oversight. The seven panic-capable serialization expect sites are unchanged by design: mcp_server/handlers/content.rs:209, mcp_server/handlers/scraping.rs:532, 691, 1002, and mcp_server/handlers/url_utils.rs:70, 80, 207 (all expect("serializing JSON to a string cannot fail")). Each carries an explicit #[allow(clippy::expect_used)] under a crate-wide deny; each operand is a serde_json::Value, a total Serialize; and a panic there is contained into isError: true at the dispatch boundary (row B1) without killing the session. The correct remedy — a proven-total serialization boundary or an explicit internal_error mapping — would be a behavioural change, not a refactor, and the issue explicitly warns that blind replacement is churn. Recorded here so the next reader does not re-open it as a bug.

Overlapping, not duplicated here: EC-08's message-language half overlaps #1604, which normalizes operational error event text to structured fields. #1604 does not own the message-language or machine-readable-reason halves; those are decided on this page.


Appendix — construction-site inventory

Counted in crates/webfang_mcp/src/mcp_server/ in the working tree — that is, commit ccdef614 plus the uncommitted reason-slug changes described under EC-08 — production code only (test modules and doc comments excluded). ccdef614 is the base, not a clean checkout: validation.rs, path_gate.rs, handlers/export.rs and handlers/scraping.rs are all dirty in this tree.

How the counts were derived — each row is a grep for one construction form, restricted to the mcp_server/ tree, with comment-only lines dropped by a /// / //! filter. Two counts deserve a note rather than a bare number:

  • provenance::neutralized_error is counted as production call sites, so the fn neutralized_error definition and every #[cfg(test)] call are excluded. That leaves 37, of which 2 are the honest_error wrapper bodies and 4 are the mapper helpers slice 4 introduced; the 31 remaining are the same direct handler-body calls the previous revision of this table counted (that figure reproduces exactly at 763714b6, which is the cross-check that the method is stable).
  • Channel C has no neutralized_error/CallToolResult::error sites at all, and its local_text sites are only 5. The old "10 construction sites across 6 conditions" is not reproducible by any single grep; the honest number is 5 local_text sites across 3 standalone conditions, plus C2, which is a field inside a success payload rather than a construction of one.
ChannelConstruction formSitesAccounted for
AMcpError::invalid_params called directly4 — the one surviving factory (mcp_server/validation.rs:110) and the SSRF channel (mcp_server/ssrf.rs:122, 135, 178)A5, A6, A9
Avalidation::invalid_params_with_reason branches (the validation funnel)44 — all in mcp_server/validation.rs (lines 139–756)A3.1–A3.9
Avalidation::invalid_params_with_reason call sites in params.rs6 — mcp_server/params.rs:97, 155, 176, 463, 527, 536A1, A3.4, A3.5, A3.6, A3.7
Avalidation::invalid_params_with_reason call sites in path_gate.rs6 — mcp_server/path_gate.rs:282, 289, 298, 309, 327, 345A4.1–A4.6
Avalidation::invalid_params_with_reason call sites in handlers/export.rs8 — mcp_server/handlers/export.rs:197, 210, 235, 252, 326, 364, 410, 470A10–A12
Avalidation::invalid_params_with_reason call sites in handlers/scraping.rs2 — mcp_server/handlers/scraping.rs:458, 605A13, A14
AMcpError::internal_error9 — mcp_server/handlers/scraping.rs:106, 109, 212, 215, 1121, 1127; mcp_server/macros.rs:16; mcp_server/ssrf.rs:154, 166A7, A8, A15, A16
Are-raised Err(e) — forwarding, not a construction1 — mcp_server/handlers/axtree.rs:74A17
Bprovenance::neutralized_error called directly37 — 31 in handler bodies + 2 honest_error wrapper bodies (handlers/ai.rs:41, handlers/axtree.rs:27) + 4 in the slice-4 mapper helpers (handlers/assets.rs:120, handlers/content.rs:241, handlers/scraping.rs:1251, handlers/obsidian.rs:134)B1–B8
Bhonest_error wrapper definitions2 — mcp_server/handlers/ai.rs:40, mcp_server/handlers/axtree.rs:26(definitions only)
Bcalls through those wrappers14 — mcp_server/handlers/ai.rs:124, 129, 142, 146, 164, 197, 202, 207, 265, 270; mcp_server/handlers/axtree.rs:130, 144, 176, 194B2.1, B4.4, B4.5, B6.1–B6.6
Bdirect CallToolResult::error1 — mcp_server/mod.rs:377B1
Cprovenance::local_text on a non-success outcome5 — mcp_server/handlers/url_utils.rs:68, 78; mcp_server/handlers/obsidian.rs:54, 55; mcp_server/handlers/scraping.rs:1005C1, C3, C4
Cper-item failure records inside a success payload (not a standalone construction)2 payloads — mcp_server/handlers/scraping.rs:372, 519C2
0HTTP status producers in this crate6 — mcp_server/auth.rs:59; mcp_server/server.rs:223, 225, 279, 311, 672T1–T5, T9
0HTTP status producers owned by rmcp's StreamableHttpService3 — not constructed here; enumerated in the matrix at mcp_server/server.rs:166-173T6–T8

Totals: 136 error-producing construction sites on the JSON-RPC channels (79 on A, 52 on B, 5 on C), plus 1 forwarding site and 6 in-crate HTTP status producers. Every one is accounted for by a row above; 0 unclassified. A is 4 + 44 + 6 + 6 + 8 + 2 + 9; B is 37 + 14 + 1.

Two scope statements, so the totals are not read as more than they are:

  • These are sites, not conditions. The eight invalid_params_with_reason calls in handlers/export.rs collapse into three rows (A10–A12), because several sites report the same condition for different tools; the reverse also holds, with 44 funnel branches collapsing into nine A3.x rows.
  • A1's construction site is the McpUrl::try_from branch at params.rs:97, but it is not a Channel A construction — it travels on Channel B. It appears in this inventory only because that is where its Rust error is defined; its row (A1) is a Channel B row, and no error member is emitted for it at all.