Troubleshooting¶
This page is the operator map for failures that look like "the server is broken" but are usually framing, negotiation, rebuild, auth, timeouts, or a leftover child. Exit classes are in CLI. Redacted records are in Diagnostics.
Match the exit number in scripts. Do not scrape stderr. Incomplete work is labeled incomplete; it is never an empty successful catalog.
Framing errors (stdio stdout is not JSON-RPC)¶
The child's stdout is the MCP stream. The first payload byte must be { or [. Anything else is protocol class 20.
| Symptom | Typical exit | What to do |
|---|---|---|
Banner, log line, or go run compile text on stdout |
20 |
Move logs to stderr. Rebuild, then inspect again. |
| Child prints JSON-RPC on stderr | 0 unless another failure |
stderr is never parsed as protocol. child_stderr on the diagnostic is informational. |
| Wrapper script echoes before exec | 20 |
Exec the server with no extra stdout. argv is never sh -c. |
Windows path missing .exe |
10 |
Pass the same path go build -o wrote. |
Details: Stdio servers.
Protocol negotiation¶
--protocol auto (default) probes server/discover with 2026-07-28 _meta, then may fall back to initialize. Pin --protocol 2025-11-25 or --protocol 2026-07-28 when you already know the era.
| Symptom | Typical exit | What to do |
|---|---|---|
HTTP 400 with UnsupportedProtocolVersionError (-32022), HeaderMismatch (-32020), or MissingRequiredClientCapabilityError (-32021) |
20 |
This is a modern server. Retry with a version from supported. Do not treat it as legacy HTTP+SSE. |
HTTP 400 with an empty or non-JSON body |
10 / 20 |
Then (and only then) auto may send initialize. Enable --allow-http-sse only for the deprecated two-endpoint transport. |
| stdio: unrecognized error or probe timeout | 10 / 20 |
Auto may send initialize. --protocol 2026-07-28 will not. |
--no-discover |
recorded skip, then maybe 60 |
Discover is skipped, not success. |
--command and --url together |
2 |
Pick one target. |
Session diagnostics should show requested, discovered, negotiated, and fallback. Full rules: Compatibility.
Rebuild and watch failures¶
Watch keeps the last good artifact unless you pass --no-keep-last-good.
| Symptom | What stays true |
|---|---|
Compiler error, missing go, rebuild timeout |
Class on the build event (nonzero, command_not_found, timeout). Staging is deleted. Last good binary and process stay. |
| Probe / handshake fail after a good build | New generation is killed. Previous ready generation stays current. |
Incomplete inventory or failed --smoke |
Not promoted. Not a new snapshot baseline. |
Events under .git, bin/, dist/ |
Ignored. |
--rebuild and --command are argv arrays. Do not point --command at the staging file while it is being written. Guide: Watch and rebuild.
Auth, TLS, and Origin¶
| Symptom | Typical exit | What to do |
|---|---|---|
Non-loopback http or skipped TLS verify |
2 / 10 |
Pass --insecure explicitly. It is never implied. |
401 / 403 |
10 |
Repeatable --header 'Authorization: Bearer …' or profile header_env. Values are redacted in logs. |
| Origin mismatch | 10 / 20 |
Origin is derived from the URL unless you set it in config. |
Putting a token in a committed mcpdev.toml |
n/a | Use ${TOKEN:?} or header_env. |
Guide: Streamable HTTP. Configuration: Configuration.
Timeouts and cancel¶
| Flag | Bounds |
|---|---|
--connect-timeout |
Handshake, including server/discover |
--timeout |
Individual catalog or invoke RPCs |
| Watch rebuild timeout | Staging discarded; last good kept |
Interrupt (Ctrl-C) cancels the context. Stdio shutdown is stdin close, grace, interrupt the process group, then kill. Exit 10 on connect timeout. Exit 60 if a list walk is canceled mid-page. Tests must not use wall-clock Sleep to hide these races.
Stale processes¶
Every inspect / call / test case / watch generation starts a new child. mcpdev is not a daemon. If a previous run was killed with kill -9 on mcpdev itself, the child process group may survive.
| Symptom | What to do |
|---|---|
| Port still bound after a canceled HTTP lab | Stop the lab process; mcpdev does not own unrelated servers. |
| Fixture binary still running after Ctrl-C | Unusual if mcpdev received SIGINT; check wrappers that ignore signals. |
| Watch "ready" but you edited source | Wait for debounce + rebuild + probe. Failed rebuild keeps the old process on purpose. |
ps for the artifact path, then stop that pid only if mcpdev is already gone. Do not kill -9 as the first step; stdin close is the graceful MCP shutdown.
Incomplete catalogs and diffs¶
incomplete_reasons / outcome |
Exit (default) |
|---|---|
pagination_stopped, cursor_loop, item_limit, failed list |
60 |
Diff with an incomplete side (indeterminate) |
60 |
Diff at or above --fail-on |
40 |
Empty list, status=complete |
0 |
--allow-incomplete keeps incomplete: true in JSON and exits 0. It does not rewrite the result as success-with-empty-data.
Safe reports¶
Include code, operation, transport, era, elapsed_ms, redacted message / cause, and incomplete_reasons. Omit raw Authorization values, URL userinfo, and unbounded child stderr. See Diagnostics.