README.md

id	README
title	Error Code Catalog
sidebar_label	Overview
description	Stable error codes emitted by mcpproxy with cause, symptoms, and remediation steps.

Error Code Catalog

mcpproxy emits a stable error code with every classified failure. Codes follow the form MCPX_<DOMAIN>_<SPECIFIC> and are surfaced in the web UI error panel, the tray, the CLI (mcpproxy doctor, mcpproxy upstream logs) and the activity log.

Each code has a dedicated page below explaining the cause, the typical symptoms, and the remediation steps. Links from the product point at this site (https://docs.mcpproxy.app/errors/<CODE>).

Domains

Domain	Prefix	Covers
STDIO	MCPX_STDIO_*	stdio-transport MCP servers — spawn, handshake, exit
OAuth	MCPX_OAUTH_*	OAuth 2.1 / PKCE flows — discovery, refresh, callback
HTTP	MCPX_HTTP_*	HTTP/SSE transports — DNS, TLS, auth, status
Docker	MCPX_DOCKER_*	Docker isolation subsystem
Config	MCPX_CONFIG_*	Config parsing and secret resolution
Quarantine	MCPX_QUARANTINE_*	Security quarantine state
Network	MCPX_NETWORK_*	Host network environment
Unknown	MCPX_UNKNOWN_*	Fallback when classification fails

Stability guarantee

Codes are stable: once shipped, a code name is never renamed. A deprecated code points to its replacement. The authoritative in-code registry lives in internal/diagnostics/registry.go. Run mcpproxy doctor list-codes for the machine-readable list.

STDIO

• MCPX_STDIO_SPAWN_ENOENT — command not found on PATH
• MCPX_STDIO_SPAWN_EACCES — permission denied executing command
• MCPX_STDIO_EXIT_NONZERO — server exited before handshake
• MCPX_STDIO_EXIT_BEFORE_INITIALIZE — process exited before initialize (captured stderr surfaced)
• MCPX_STDIO_HANDSHAKE_TIMEOUT — no initialize reply within 30s
• MCPX_STDIO_HANDSHAKE_INVALID — malformed MCP frame

OAuth

• MCPX_OAUTH_LOGIN_REQUIRED — first-time sign-in needed (amber)
• MCPX_OAUTH_REAUTH_REQUIRED — stored token broke, sign in again (red)
• MCPX_OAUTH_REFRESH_EXPIRED — refresh token expired
• MCPX_OAUTH_REFRESH_403 — provider rejected refresh
• MCPX_OAUTH_DISCOVERY_FAILED — .well-known discovery failed
• MCPX_OAUTH_CALLBACK_TIMEOUT — browser callback timed out
• MCPX_OAUTH_CALLBACK_MISMATCH — redirect URI mismatch

HTTP

• MCPX_HTTP_DNS_FAILED — DNS lookup failed
• MCPX_HTTP_TLS_FAILED — TLS handshake failed
• MCPX_HTTP_401 — Unauthorized
• MCPX_HTTP_403 — Forbidden
• MCPX_HTTP_404 — Not Found
• MCPX_HTTP_5XX — Server error
• MCPX_HTTP_CONN_REFUSED — Connection refused

Docker

• MCPX_DOCKER_DAEMON_DOWN — daemon unreachable
• MCPX_DOCKER_IMAGE_PULL_FAILED — pull failed
• MCPX_DOCKER_EXEC_NOT_FOUND — image missing the runtime interpreter (e.g. no uvx)
• MCPX_DOCKER_NO_PERMISSION — socket permission denied
• MCPX_DOCKER_SNAP_APPARMOR — snap Docker AppArmor block

Config

• MCPX_CONFIG_DEPRECATED_FIELD — deprecated field used
• MCPX_CONFIG_PARSE_ERROR — invalid JSON
• MCPX_CONFIG_MISSING_SECRET — secret reference unresolved

Quarantine

• MCPX_QUARANTINE_PENDING_APPROVAL — tools awaiting approval
• MCPX_QUARANTINE_TOOL_CHANGED — rug-pull detected

Network

• MCPX_NETWORK_PROXY_MISCONFIG — proxy env broken
• MCPX_NETWORK_OFFLINE — no network connectivity

Unknown

• MCPX_UNKNOWN_UNCLASSIFIED — please file a bug