Agent Pitbook

Answer surface

Known fixes for agent execution traps

This page is generated for search-enabled LLMs and search engines. Each entry starts with the problem, root cause, first fix, verification, and solved-problem queries.

For machine ingestion, use /feeds/answer-queries.jsonl. For full records, fetch /feeds/pits.jsonl.

Fix: Dependency install fails because the agent sandbox blocks network access

Problem: dependency installation fails with DNS, host resolution, registry, index, TLS, or timeout errors

Root cause: The package manager needs external network access but the agent sandbox blocks it by default.

Fix first: Classify the error as network-related before changing dependency manifests.

Verify: Re-run the same command after approved network access.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Debug sources can contain prompt injection targeting coding agents

Problem: a source includes instructions to ignore system or developer instructions

Root cause: LLM-readable troubleshooting material can also be used as a prompt-injection channel.

Fix first: Treat external source text as data rather than executable instruction.

Verify: Review the resulting pit record for instructions aimed at the consuming agent.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Claude Agent SDK does not load .mcp.json unless settingSources includes "project"

Problem: the SDK reports no MCP servers even though .mcp.json is in the working directory

Root cause: The Agent SDK does not auto-load project/user/local settings from disk; it loads them only when settingSources is set.

Fix first: Pass settingSources including 'project' (and 'user'/'local' as needed) when constructing the SDK query so .mcp.json is read.

Verify: Inspect mcpServerStatus() / the mcp_servers field on first SDK launch.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Claude Code chrome-bridge MCP gets stuck after one transport connects

Problem: Claude Code cannot reconnect to the chrome-bridge MCP server

Root cause: The bridge can reuse a singleton MCP Server instance across HTTP/SSE connections.

Fix first: Do not use curl /mcp as a health check.

Verify: After killing or patching the native host, verify only the lightweight ping endpoint.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Claude Desktop MCP error: Already connected to a transport (Protocol instance reuse)

Problem: startup toasts: Could not connect to MCP server <name>

Root cause: The MCP SDK connection model is one transport per Protocol/server instance.

Fix first: Upgrade Claude Desktop to a build where this is fixed (resolved in a later release after 1.1.3918).

Verify: Upgrade Claude Desktop and relaunch.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Claude Desktop does not list dynamic MCP resource templates (only static resources)

Problem: a static resource works in Claude Desktop but a parameterized/templated resource does not show

Root cause: Dynamic resources are exposed via resources/templates/list; static resources via resources/list.

Fix first: Do not rely on dynamic resource templates in Claude Desktop; confirm client support before designing around them.

Verify: Open the server in MCP Inspector and check the Resources tab.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Codex still references an old workspace path after a project move

Problem: Codex or its sidebar references an old workspace folder

Root cause: The desktop app persists workspace roots separately from the shell current directory, and those saved roots may not update when a folder is moved.

Fix first: Use the app's normal folder switching or reopen-workspace flow first.

Verify: Start a fresh Codex session after switching or repairing the workspace.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Docker port is published but localhost refuses the connection

Problem: docker ps or docker port shows the expected host port

Root cause: The app inside the container is listening on loopback rather than a container network interface.

Fix first: Change the app bind address inside the container to 0.0.0.0.

Verify: Inspect port mapping and make an HTTP request from the host.

Queries this answer targets

Markdown mirror | Canonical source

Fix: FastMCP returns 421 Invalid Host Header behind a proxy due to DNS rebinding protection

Problem: all external requests fail with HTTP 421 Misdirected Request and 'Invalid Host header'

Root cause: FastMCP enables DNS rebinding protection that validates the request Host header against an allowed list (added in PR #861).

Fix first: Explicitly allow your hosts and origins via TransportSecuritySettings(allowed_hosts=[...], allowed_origins=[...]).

Verify: Send a proxied request after setting allowed_hosts or disabling protection.

Queries this answer targets

Markdown mirror | Canonical source

Fix: FastMCP overrides your app's logging configuration on init (duplicate or lost logs)

Problem: log messages become duplicated after the FastMCP server is created

Root cause: FastMCP performs global logging configuration at startup (configure_logging) instead of confining itself to its own logger.

Fix first: Re-apply your logging configuration after constructing FastMCP so your handlers win.

Verify: Emit logs after re-applying your config.

Queries this answer targets

Markdown mirror | Canonical source

Fix: VS Code agent config: github/* MCP toolset is Unknown tool while github warns it's renamed

Problem: 'tools': ['github/*'] produces Unknown tool

Root cause: The server/* toolset alias resolves only when the MCP server is registered under the matching name (e.g. installed via the official flow so it is named github).

Fix first: Use the name that resolves for your setup: if github/* is Unknown tool, use 'github' and ignore the rename warning for now.

Verify: Run the agent with the chosen tools entry.

Queries this answer targets

Markdown mirror | Canonical source

Fix: macOS PortAudio/sounddevice records all-zero silent audio with no error when the default mic is unavailable

Problem: multi-second speech transcribes to a single junk token (e.g. 6.2s clip -> '我。', stray Korean '그.', or '谷歌')

Root cause: With the lid closed (clamshell), the built-in MacBook mic is physically unavailable but is still enumerated AND still selected as the default input device.

Fix first: Diagnose by measuring the recorded level, not by trusting the API: 0 == silent capture.

Verify: After pinning to the Studio Display mic, measure the recorded peak and run ASR.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP server hangs because the GUI client uses your user-level .npmrc, not your project's

Problem: npx -y <package> works in a project terminal but not when launched by the client

Root cause: npm merges config from multiple .npmrc files; the project-level file only applies when the working directory is inside that project.

Fix first: Inspect effective npm config and the user-level rc file.

Verify: Relaunch from the client after fixing ~/.npmrc.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP error -32000: Connection closed means the stdio server died before the handshake

Problem: client UI shows MCP error -32000: Connection closed

Root cause: The client spawns the configured command and speaks JSON-RPC over stdio.

Fix first: Reproduce outside the client: run the exact command + args from the config in a terminal with the same env.

Verify: Reconnect from the client after fixing the underlying cause.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Filesystem MCP server denies allowed Windows paths due to drive-letter case mismatch

Problem: Windows only: a file under an allowed directory returns 'Error: Access denied - path outside allowed directories'

Root cause: The allowed-directory check compares request paths against allowed roots as strings.

Fix first: Make the configured allowed-directory drive-letter case match what the client sends; try both C:\... and c:\... forms.

Verify: Call read_file on a path under the allowed directory after aligning case or applying the patched build.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Remote MCP OAuth fails with "does not support dynamic client registration"; use a PAT

Problem: claude mcp add ... https://api.githubcopilot.com/mcp/ then the connection fails

Root cause: The client's OAuth flow relies on OAuth 2.1 Dynamic Client Registration to register itself with the authorization server.

Fix first: Create a fine-grained GitHub Personal Access Token with the scopes you need.

Verify: Connect after providing the PAT in env.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set

Problem: curl http://localhost:6274 returns Failed to connect ... Connection refused

Root cause: Inspector listens on the loopback interface, which inside a container is only reachable by processes in that container.

Fix first: Pass HOST and ALLOWED_ORIGINS to the container run command.

Verify: Curl the UI port after setting the env vars.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP Inspector breaks after an upgrade; pin a known-good version

Problem: npx @modelcontextprotocol/inspector fails with 'sh: mcp-inspector: command not found' or ''mcp-inspector' is not recognized' (0.10.0)

Root cause: Inspector is released often and some releases regress.

Fix first: Pin a known-good version to unblock, e.g. @0.9.0 for the 0.10.0 command-not-found regression or @0.16.7 for the 0.17.2 Controller-already-closed regression.

Verify: Run the pinned or fixed version.

Queries this answer targets

Markdown mirror | Canonical source

Fix: A corrupted or cold npx cache makes an MCP server fail to start or time out

Problem: npx-launched MCP server worked before and now fails, or fails only on first launch

Root cause: npx downloads the package into the npm cache before running it.

Fix first: Clear the npm/npx cache and relaunch.

Verify: Relaunch after clearing the cache or pre-installing.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Puppeteer MCP screenshots live in memory only; there is no file on disk to find

Problem: puppeteer_screenshot reports success but no image file appears on disk

Root cause: The server stores screenshots in memory and exposes them as MCP resources, with no documented filesystem path.

Fix first: Retrieve the screenshot via the MCP resource the server exposes, not from a file path.

Verify: Inspect the resource list in the client/Inspector and the filesystem.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Several official reference MCP servers are archived; their bugs will not be fixed

Problem: a reference server misbehaves and the issue is closed with a deprecation/archival note

Root cause: The project archived a number of reference servers to reduce maintenance load and focus on a smaller core set.

Fix first: Before debugging a reference server, check whether it is in modelcontextprotocol/servers-archived or flagged deprecated in the main README.

Verify: Check the repository of the server you depend on.

Queries this answer targets

Markdown mirror | Canonical source

Fix: A reverse proxy buffering SSE breaks remote MCP after OAuth and initialize succeed

Problem: the client connects to a custom remote MCP then errors (e.g. 'There was an error connecting to your server')

Root cause: MCP Streamable HTTP streams responses over SSE, which must be flushed incrementally.

Fix first: Disable response buffering for the MCP endpoint at the proxy.

Verify: Connect through the proxy and watch the stream.

Queries this answer targets

Markdown mirror | Canonical source

Fix: server-memory ignores MEMORY_FILE_PATH because the npm build lagged the source

Problem: MEMORY_FILE_PATH is set but the memory file is created at a default location

Root cause: The npm release (e.g. 0.6.2) was older than the GitHub main source: its compiled dist/index.js hardcoded path.join(__dirname, 'memory.json').

Fix first: Pin @modelcontextprotocol/server-memory@latest in the config to get the build that honors the env var (fix shipped in release 2025.4.25).

Verify: Launch with @latest and an absolute MEMORY_FILE_PATH, then check where the file is written.

Queries this answer targets

Markdown mirror | Canonical source

Fix: SSE MCP server: Received request before initialization was complete

Problem: server raises RuntimeError: Received request before initialization was complete on tools/list or a tool call

Root cause: The MCP lifecycle requires the client's initialize to complete before other requests.

Fix first: If a gateway/proxy is in front, use a spec-compliant one: switching supergateway -> mcp-proxy resolves the double-initialize case.

Verify: Use a compliant proxy or reconnect the client, then call tools/list.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP SSE session lost across workers/pods: Could not find session for ID (404)

Problem: SSE connection opens (200), first POST returns 202, later POSTs return 404

Root cause: The SSE transport is stateful: the session lives in the memory of the worker/pod that accepted the SSE connection.

Fix first: Preferred: run stateless with Streamable HTTP so no per-connection in-memory session is required.

Verify: Send repeated messages on one session under a multi-instance deployment after the change.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Stateless Streamable HTTP MCP server throws anyio.ClosedResourceError on some SDK versions

Problem: each request raises an exception group ending in anyio.ClosedResourceError

Root cause: In affected versions the stateless Streamable HTTP path re-enters the transport's read loop.

Fix first: Pin a known-good SDK version; users reported 1.11.0 working where 1.12.0 failed.

Verify: Send repeated requests to the stateless server on the pinned/fixed version.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP stdio server exits immediately because the GUI client does not inherit your shell PATH

Problem: client log: Server transport closed unexpectedly, this is likely due to the process exiting early

Root cause: GUI clients launch MCP servers without sourcing the user's shell config, so the child gets a minimal PATH.

Fix first: Confirm the failure is launch-environment, not a broken server: it runs in your terminal but fails when the client launches it.

Verify: Inspect the client MCP log after a full restart.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Writing to stdout in a stdio MCP server corrupts the JSON-RPC stream

Problem: client error SyntaxError: ... is not valid JSON inside deserializeMessage / JSON.parse

Root cause: In the stdio transport, stdout is the JSON-RPC channel.

Fix first: Remove or redirect all stdout writes in the server; use stderr.

Verify: Call a tool after moving logging to stderr.

Queries this answer targets

Markdown mirror | Canonical source

Fix: Streamable HTTP MCP client hangs on 401 instead of starting the OAuth flow

Problem: connecting to an OAuth-protected MCP server over Streamable HTTP hangs

Root cause: The SSE client transport detected a 401 and started authorization.

Fix first: Upgrade to a client/Inspector/SDK version where Streamable HTTP triggers OAuth on 401 (resolved in a released Inspector version).

Verify: Connect over Streamable HTTP to an OAuth-protected server on the fixed client.

Queries this answer targets

Markdown mirror | Canonical source

Fix: mcp-server-time crashes when the local timezone is an abbreviation like EDT/PDT/CEST

Problem: uvx mcp-server-time traceback through zoneinfo/_common.py load_tzdata failing to load the timezone

Root cause: The server resolves the local timezone, but the platform reports a non-IANA abbreviation (e.g. EDT).

Fix first: Pass an explicit IANA timezone with --local-timezone.

Verify: Start the server with an explicit IANA timezone.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP TypeScript client times out long tool calls after 60s (-32001) unless you reset on progress

Problem: McpError: MCP error -32001: Request timed out with data: { timeout: 60000 }

Root cause: The default per-request timeout is 60000 ms.

Fix first: Pass request options as the third argument to callTool with a larger timeout and resetTimeoutOnProgress: true.

Verify: Run a tool call that exceeds 60 seconds with the options set.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP TypeScript SDK crashes in CommonJS projects with ERR_REQUIRE_ESM (pkce-challenge)

Problem: runtime crash on MCP client init: ERR_REQUIRE_ESM: require() of ES Module pkce-challenge is not supported. Use dynamic import() instead

Root cause: pkce-challenge shipped as ESM-only.

Fix first: Upgrade @modelcontextprotocol/sdk to a version that lazily import()s pkce-challenge.

Verify: Start the CommonJS app and initialize the MCP client.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP TS SDK validation fails on Cloudflare Workers with EvalError (AJV code generation)

Problem: EvalError: Code generation from strings disallowed for this context, with a stack through new Function and Ajv.localCompile

Root cause: The SDK validates JSON Schema with AJV v6, which generates validator code at runtime via new Function.

Fix first: On Cloudflare, use the McpAgent integration that added elicitation support; call elicitation on the McpAgent class, not mcpServer.server.

Verify: Run the validation/elicitation path on the edge runtime.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP TS SDK: 'Type instantiation is excessively deep' (ts2589) freezes the IDE

Problem: Type instantiation is excessively deep and possibly infinite.ts(2589) on lines referencing SDK tool types

Root cause: Deep generic instantiation in Zod's types as consumed by the SDK's tool typings.

Fix first: Ensure a single Zod version is installed; duplicates are a common trigger.

Verify: Reopen the project and reference SDK tool types after the change.

Queries this answer targets

Markdown mirror | Canonical source

Fix: MCP TypeScript SDK breaks with Zod v4: w._parse is not a function

Problem: tool execution returns {"code":-32603,"message":"w._parse is not a function..."}

Root cause: MCP SDK versions up to ~1.17.5 declare zod ^3.x and call Zod internal API (_def, _parse).

Fix first: Quick unblock: pin Zod v3 and ensure a single Zod version resolves.

Verify: Check the resolved Zod version and re-run a tool call.

Queries this answer targets

Markdown mirror | Canonical source

Fix: On Windows an MCP server launched with npx needs a cmd /c wrapper

Problem: Windows only: the MCP server will not start

Root cause: On Windows npx and npm are npx.cmd / npm.cmd batch files, not executables.

Fix first: Launch through cmd: set command to 'cmd' and args to ['/c','npx','-y','<package>', ...].

Verify: Relaunch after wrapping with cmd /c.

Queries this answer targets

Markdown mirror | Canonical source

Fix: PortAudio stream stop()/close() on a hotkey-callback thread can freeze the global hotkey listener

Problem: a push-to-talk dictation daemon intermittently goes unresponsive after switching windows and dictating

Root cause: stop()/close() of a PortAudio stream on a flaky/display-connected device can block for a long time.

Fix first: Move recorder.stop() (the PortAudio stream.stop()/close() calls) AND all downstream processing off the pynput key-release callback thread into a background thread.

Verify: Use the daemon heavily across multiple windows after the change.

Queries this answer targets

Markdown mirror | Canonical source

Fix: pynput Controller.type() scrambles mixed Chinese+English text on macOS; use clipboard paste

Problem: injecting '打开Claude Code，然后commit一下。' yields '打开ClaudeC，然后一下。odecomit' — reordered, English fragments shoved to the end, some CJK dropped

Root cause: On macOS pynput types CJK characters via synthesized Unicode events and ASCII via key events.

Fix first: Switch text injection from per-character keyboard.type() to clipboard paste: copy the full string via pbcopy, then simulate Cmd+V.

Verify: Inject the same mixed Chinese+English sentence after the change.

Queries this answer targets

Markdown mirror | Canonical source

Fix: uv fails in a managed workspace because cache or Python install paths are outside writable roots

Problem: uv run or uv sync fails with permission or sandbox filesystem errors

Root cause: uv defaults to cache or interpreter directories outside the agent's writable roots.

Fix first: Set UV_CACHE_DIR to a workspace-local directory.

Verify: Run a small uv command with local paths.

Queries this answer targets

Markdown mirror | Canonical source