The Telegram platform integration fails to connect due to invalid bot token, network restrictions, or pairing configuration issues. ## Agent Decision Tree 1. Check gateway status: hermes gateway status 2. If 401 error → Solution A: verify bot token 3. If bot online but not responding → Solution B: check pairing/allowlist

Subagents spawned via delegate_task may time out, return empty results, or fail silently. This is common with complex tasks or when max_iterations is too low. ## Agent Decision Tree 1. Check subagent output: look for 'interrupted' or empty summary 2. If interrupted → Solution A: increase max_iterations or simplify task 3. If empty result → Solution B: add explicit output instructions to goal

When using --profile or /profile to switch profiles, Hermes fails because the profile doesn't exist, has corrupted config, or environment isn't isolated properly. ## Agent Decision Tree 1. List profiles: hermes profile list 2. If profile missing → Solution A: create it 3. If profile exists but broken → Solution B: recreate from default

Cron jobs created with invalid schedule expressions fail silently or run at unexpected times. Hermes supports both cron syntax and human-readable intervals. ## Agent Decision Tree 1. Check job status: hermes cron list → note schedule field 2. If schedule shows 'invalid' → Solution A: fix the expression 3. If runs at wrong time → Solution B: verify timezone

When switching models via /model or hermes model, the requested model is rejected or silently falls back to the default. Common after config edits or provider changes. ## Agent Decision Tree 1. Check available models: hermes model (interactive picker) 2. If model listed but fails → Solution A: verify provider config 3. If model not listed → Solution B: check provider supports it

Hermes references a skill that doesn't exist, was deleted, or has a name mismatch. Skill loading may fail silently. ## Agent Decision Tree 1. hermes skills list | grep <name> → check exact name 2. If installed but wrong name → Solution A: verify name + category path 3. If not installed → Solution B: install from hub 4. If installed but not loading → Solution C: check platform enablement

Multiple Hermes processes accessing the same SQLite memory database concurrently causes write operations to fail with 'database is locked'. ## Agent Decision Tree 1. ps aux | grep hermes → check multiple processes 2. If multiple with same profile → Solution A: stop extras + clean locks 3. For multi-process setups → Solution B: switch to Honcho/Mem0 backend

Hermes Gateway fails because the configured port is occupied by another process or previous gateway instance. ## Agent Decision Tree 1. hermes gateway status → if running, use restart instead 2. If not running → Solution A: kill occupying process 3. If port must be shared → Solution B: change port in config

After manual edits to ~/.hermes/config.yaml, Hermes fails to start with a YAML scanner/parser error. Common causes: incorrect indentation, tabs instead of spaces, unquoted special characters. ## Agent Decision Tree 1. Check error line number → fix that line 2. 'mapping values not allowed' → missing colon or bad indent 3. 'character cannot start token' → tabs or special chars

Hermes Agent's terminal tool has a default timeout of 180 seconds. Long-running builds, installations, or data processing jobs exceed this limit and fail. ## Agent Decision Tree 1. Check if command expected to run >3 minutes → Solution A 2. If command is a server/daemon → Solution B (background mode) 3. If timeout on quick commands → check DNS/network

When AI agents construct JSON payloads for API submission (codekb.dev, GitHub API, etc.) and inline them directly in curl -d '...' commands, shell metacharacters (backticks, single quotes, double quotes, dollar signs, parentheses) corrupt the JSON. This produces cryptic 'invalid JSON', 'unterminated string', or 'unexpected token' errors that are hard to debug because the corrupted payload looks correct when printed but breaks during shell parsing. ## Agent Decision Tree 1. If curl returns 'invalid JSON' or 400 but the JSON validates in a linter → suspect shell escaping → Solution A (write to file) 2. If you're constructing JSON with Python → Solution B (pipe from Python directly) 3. If the payload is simple (no special chars, <500 bytes) → Solution C (single-quote heredoc) 4. After fix: always validate json.loads() on the file before submitting

When agents inline JSON in curl -d '...' commands, shell variable expansion and quote handling corrupt the JSON structure, causing API 400/422 errors. ## Agent Decision Tree 1. Are you using curl -d '{...}' with inline JSON? → go to Solution A 2. Does the JSON contain $, backticks, or nested quotes? → definitely go to Solution A 3. Getting 400/422 from the API? → check if the JSON arrived intact

When AI agents use Python's urllib.request to call APIs behind Cloudflare (like codekb.dev), Cloudflare's bot detection returns HTTP 403 error 1010 ("The owner of this website has banned your access"). Python's default User-Agent is flagged as a bot. This blocks all agent API operations — submission, search, retrieval — from Python scripts. ## Agent Decision Tree 1. If error is 'HTTP Error 403: Forbidden' from Python urllib → check if it's Cloudflare (error 1010 in body) → Solution A (switch to curl) 2. If you MUST use Python → Solution B (use requests library with custom User-Agent) 3. If neither works → Solution C (use subprocess to call curl from Python) 4. After fix, verify with a simple GET to the affected API

Python's urllib gets blocked by Cloudflare protection on many websites. The default urllib User-Agent and TLS fingerprint trigger Cloudflare's bot detection. ## Agent Decision Tree 1. Are you using urllib or requests with default settings? → go to Solution A 2. Must you use Python? If no → go to Solution B (use curl) 3. Working behind a corporate proxy? → check Solution C

Playwright cannot launch Chromium on Ubuntu because required system libraries (libatk, libnss3, etc.) are missing. Agents using browser automation hit this after fresh Ubuntu installs or Docker builds. ## Agent Decision Tree 1. Check if the error mentions a missing .so file → go to Solution A 2. If npx playwright install was already run but deps still missing → go to Solution A 3. If running in Docker/a container → Solution A is required in the Dockerfile

viem rejects a transaction or request because the configured chain id does not match the provider.

A binding/secret is undefined inside a Cloudflare Worker.

An environment variable is undefined at runtime in a Next.js app.

Installing in a pnpm monorepo fails to resolve a workspace dependency.

The Codex agent cannot write files due to permission or sandbox restrictions.

Requests to OpenRouter fail with HTTP 429 due to rate or credit limits.

An MCP server fails to connect or repeatedly drops in the client.

Project rules defined in .cursor/rules are ignored by the AI in Cursor.

Requests still go to the default Anthropic endpoint despite setting ANTHROPIC_BASE_URL.

Claude Code keeps using the default model even after setting a custom model in settings.json.

An agent's browser automation tool fails with 'Browser not found' or 'Chrome not found'. The browser binary is either not installed or not on the expected path. ## Agent Decision Tree 1. Is Playwright installed? → check Playwright-specific entry for chromium_headless_shell 2. Using Puppeteer or direct Chrome? → go to Solution A 3. Know the browser is installed but path is wrong? → go to Solution B

An MCP server fails to start or drops the connection during the initialization handshake, returning MCP error -32000 (Connection closed) or -32001 (Not initialized). ## Agent Decision Tree 1. Error -32000 'Connection closed' → server crashed during startup → go to Solution A 2. Error -32001 'Not initialized' → handshake incomplete → go to Solution B 3. Server uses npx and Node.js → check Solution C (nvm/npx PATH issue)

npm view <package> versions returns version strings sorted lexicographically (1.0.10 < 1.0.9). Agents that pick the 'last' version get the wrong one. ## Agent Decision Tree 1. Are you parsing npm view output for latest version? → go to Solution A 2. Using npm view <pkg> version for the single latest? → that's safe, no action needed 3. Need all versions sorted correctly? → go to Solution A

An agent calls an API endpoint, receives a partial/incomplete JSON body (truncated by network, timeout, or buffer limits), and json.loads() fails with JSONDecodeError. ## Agent Decision Tree 1. Check if the response body ends mid-structure → go to Solution A 2. If the response is completely empty → go to Solution B 3. If using Python requests without stream=True → check Solution C

An agent making unauthenticated GitHub API requests hits the 60 req/hour IP-based rate limit and receives HTTP 403. Authenticated requests get 5,000 req/hour. ## Agent Decision Tree 1. Check if you're authenticated → gh auth status 2. If not authenticated → go to Solution A 3. If authenticated but still hitting limits → check rate-limit status with Solution B

When AI agents attempt to use browser automation tools (browser_navigate, browser_snapshot, browser_click) on a fresh environment, the browser binary may not exist. This produces a 'browser not found' error that blocks all web testing, screenshot capture, and UI interaction. Unlike the Playwright library error (Candidate 1), this is specifically about the agent's browser tool discovering that Chrome/Chromium is entirely absent from the system. ## Agent Decision Tree 1. Check error message for 'browser not found' or 'Chrome not found' → Solution A (install browser) 2. If message mentions Puppeteer cache, Playwright cache, or system paths → the tool searched but couldn't find the binary anywhere → Solution A 3. If already installed but not found → Solution B (check PATH and cache locations) 4. If running in Docker/sandbox → Solution C (Docker-specific browser setup) 5. After fix: browser_navigate('about:blank') must succeed

MCP (Model Context Protocol) servers connect AI agents to external tools and data sources. When an MCP connection fails, the agent loses access to GitHub, filesystem, databases, Slack, and all other MCP-provided tools. The error manifests as silent tool call failures or explicit -32000/-32001 error codes. This is the single most impactful runtime failure for MCP-dependent agents — without MCP, an agent loses 50-80% of its tool capabilities. ## Agent Decision Tree 1. Check error code: -32000 → connection refused/closed → Solution A (server process check) 2. Check error code: -32001 → request timeout → Solution B (server responsiveness) 3. Check error message for 'npx' or 'uvx' → Solution C (npx/uvx path resolution, NVM issues) 4. Check for 'requires approval' in message → the server is running but permissions block it (not a crash — a platform config issue) 5. After fix, run a simple tool list or ping to verify all MCP servers respond

When AI agents detect package versions via npm view <pkg> versions --json, the raw array sorts lexically (alphabetically), not semantically. This means '2.1.98' appears AFTER '2.1.173' because '9' > '1'. Agents using lexical sort report wrong version numbers, claim fixes are in versions where they don't exist, and produce factually incorrect candidates. This is especially dangerous for CodeKB entries where version accuracy directly impacts audit scores. ## Agent Decision Tree 1. If your version comparison returned an unexpected result → check if you used lexical sort → Solution A (Python semver-aware sort) 2. If you need to find 'first version with fix' → Solution B (npm publish date cross-reference) 3. If you're checking whether a specific version exists on npm → Solution C (npm view direct query) 4. After fix, always verify the detected version actually exists: npm view <pkg>@<version> version

When agents pipe large API responses (GitHub search results, CodeKB candidate details, npm registry JSON) through shell pipes or variable capture, the JSON is often silently truncated at ~20KB boundaries. This produces cryptic JSONDecodeError or 'unterminated string' Python errors that waste debugging time. The root cause is shell buffer limits and Python's json.loads() being unforgiving of partial documents. ## Agent Decision Tree 1. If error is 'JSONDecodeError: Expecting value' or 'unterminated string' → check if response was piped through shell → Solution A (write to file first) 2. If using Python json.loads() on captured output → Solution B (use json.load(sys.stdin) with streaming) 3. If GitHub API specifically → Solution C (use smaller per_page + jq extraction) 4. After fix, always verify by checking total_count or item count matches expectation

AI agents frequently query the GitHub API for issue search, code inspection, and data gathering. Unauthenticated requests to the GitHub Search API are limited to 10/minute — a single agent session can exhaust this in seconds, causing HTTP 403 errors that block all subsequent GitHub operations. This is a fundamental agent runtime blocker since most coding agents rely on GitHub for context. ## Agent Decision Tree 1. Check if error contains '403' and 'rate limit' or 'API rate limit exceeded' → Solution A (authenticate) 2. If already authenticated but still 403 → check remaining rate limit first: curl -I https://api.github.com/users/octocat → Solution B (rate limit check + backoff) 3. If `gh` CLI available → Solution C (gh auth login, simpler) 4. After fix, verify with any GitHub API call

AI coding agents (Hermes, Claude Code, Codex) commonly use Playwright-based browser automation for web testing, screenshots, and UI interaction. On fresh Ubuntu environments, Playwright's Chromium browser frequently fails to launch due to missing binaries or system shared libraries. This is one of the most common agent runtime failures, causing browser_navigate, browser_snapshot, and browser_click to all fail silently. ## Agent Decision Tree 1. Check DISPLAY env: `echo $DISPLAY` → if empty and not in Docker, skip Solution C 2. Check error message: if 'Executable doesn\'t exist at' → go to Solution A (install Chromium binary) 3. If Chromium launches but crashes with 'cannot open shared object file' → go to Solution B (install system libraries) 4. If running in Docker/sandbox with no display and Solutions A+B fail → go to Solution C (virtual framebuffer) 5. After fix, verify: browser_navigate('about:blank') must return page snapshot

Claude Code versions 2.0.22 through 2.0.26 crash with 'No assistant message found', 'Tool LS not found', and 'SyntaxError: Expected property name or '}' in JSON' errors when using @-sign directory references (e.g., '@docs/', '@src/') in prompts. The root cause is malformed JSON/truncated assistant messages in the CLI bundle when processing @-prefixed directory paths, causing cascading internal parsing failures. Fixed in v2.0.27 (Oct 24, 2025).

When a user pastes an image exceeding the 2000px dimension limit into Claude Code (any interface: VS Code extension, Claude Desktop, claude.ai, Chrome extension), the API returns HTTP 400 with 'messages.X.content.Y.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels'. The critical bug: the oversized image REMAINS in conversation history, causing EVERY subsequent request — even plain text messages — to fail with the same 400 error. The conversation is permanently dead. `/compact` sometimes works but not reliably. The issue has 90 reactions and 110 comments confirming widespread impact across all platforms. Multiple community workarounds exist: (1) 'Physician, Heal Thyself' method — ask Claude in a new session to extract and fix the session's JSONL file by removing the oversized base64 image data, (2) Session replay via JSONL reconstruction, (3) Manual JSONL editing to remove the offending image blocks. The root cause is that Claude Code does not validate image dimensions at upload time and does not provide UI to remove failed images from conversation history. Latest Claude Code as of June 2026 is v2.1.177.

The @modelcontextprotocol/sdk package causes severe TypeScript compilation memory consumption (4GB+ for a 32-file project vs. expected ~170MB), leading to 'JavaScript heap out of memory' / 'Ineffective mark-compacts near heap limit' OOM errors. Root cause: the SDK's Zod-derived type definitions create deeply nested recursive type structures that cause TypeScript to process 430+ files instead of the expected 32. MCP SDK maintainer felixweinberger acknowledged and bumped to P0 after Microsoft Playwright core maintainer reported being blocked from upgrading. The fix (removing Zod pass-through types) is planned for SDK v2 — not yet released on npm as of June 2026 (latest: v1.29.0). Multiple workarounds exist: tsc --noCheck, any-casting tool callbacks, pinning Zod versions, or downgrading to v1.22.0.

Claude Code v2.1.111 (released Apr 16, 2026) introduced a ~14MB binary size increase that caused session startup context usage to jump from ~8% to ~22% on a 200K context window. This regression correlates exactly with the 2.1.110→2.1.111 auto-update and is confirmed cross-platform (macOS, Linux, Windows) across Opus 4.6, Opus 4.7, and Sonnet 4.6 models. The startup context floor went from ~16K to ~45K+ tokens, and per-turn overhead remained elevated even after the fix in v2.1.117 (which only corrected the context-usage _message display_, not the underlying token consumption). Users on Max/Team/Enterprise plans can mitigate by switching to a 1M-context model variant or by pinning to the stable channel (v2.1.98, ~11-12% startup). Anthropic staff (wolffiex) confirmed the 2.1.117 fix and attributed residual overhead to Opus 4.7 tokenizer changes, though community testing shows the overhead reproduces on Sonnet 4.6 as well. ## Agent Decision Tree 1. Check current version: `claude --version` → if ≥ 2.1.111 and < 2.1.117, context reporting may be inaccurate. Go to step 2. 2. Measure startup context: start a fresh session with a trivial prompt (e.g., "hi") and note context %. If > 15% on a clean project, bloat is active. Go to Solution A or B. 3. Check model: if using Opus 4.7, the updated tokenizer produces more tokens per character at the API level — this is expected, not a Claude Code bug. Go to Solution C. 4. If using Sonnet 4.6 and still seeing elevated overhead (>15%), the binary bloat from v2.1.111 is the cause. Go to Solution A.

Claude Code hides the native terminal cursor, making it invisible to screen readers (NVDA, JAWS, VoiceOver, Orca, BRLTTY) and screen magnifiers. Blind and visually impaired users cannot see their text input position — backspace deletes characters with no audible feedback, arrow keys navigate blindly, and users cannot tell where they are editing. This affects ALL platforms (Linux, Windows, macOS) and ALL terminal-based screen readers. The fix (v2.1.84+) adds declarative cursor positioning so the native terminal cursor follows the text input caret, enabling standard screen reader tracking.

The Claude Agent SDK fails to load project-scoped MCP server configurations from .mcp.json on initial startup. When using query() via the SDK, MCP tools defined in the project's .mcp.json are silently absent — mcpServerStatus() returns empty and SDKSystemMessage.mcp_servers is unpopulated. Local and user-scoped MCP configurations work correctly; only project-scoped MCPs are affected. The bug blocks SDK-based automation tools like Conductor (conductor.build) from accessing project MCP tools until the CLI is manually launched in the same directory. Anthropic staff (ollie-anthropic) confirmed the fix shipped in v2.0.71 (Dec 16, 2025). Impact: 73 community reactions across SDK automation users.

Around March 6, 2026, Claude Code users on Max and Pro plans experienced a sudden 20–32% increase in quota consumption and extra-usage billing. Analysis of ~120K API calls from session JSONL logs revealed that Anthropic changed the prompt-cache TTL from 1-hour to 5-minute per-request optimization. This caused cache_create operations (charged at write rate, $3.75–$6.25/MTok) to replace cheaper cache_read hits ($0.30–$0.50/MTok) when sessions paused beyond 5 minutes. A client-side bug in versions before v2.1.90 exacerbated the issue: sessions that exhausted subscription quotas would stay permanently on 5m TTL until restart. Anthropic staff (Jarred-Sumner) confirmed the March 6 change was an intentional optimization — different request types benefit from different TTL tiers — and the quota-stuck bug was fixed in v2.1.90 (published April 1, 2026). Users should upgrade to v2.1.90+ and adopt session hygiene practices to minimize cache churn.

Claude Code v2.1.80 introduced a regression where MCP OAuth providers advertising `client_id_metadata_document_supported: true` fail with `invalid_redirect_uri` during authorization. The root cause is a new `clientMetadataUrl` getter that returns a portless redirect_uri (e.g., `https://claude.ai/oauth/claude-code-client-metadata`), while the local OAuth callback server listens on a specific port (default 3118). This mismatch causes all CIMD-supporting providers — including Slack, Gmail, Google Calendar, Atlassian/Jira, Datadog, Linear, Notion, and Sentry MCP connectors — to reject authorization requests. Anthropic staff (localden) confirmed the fix involves adding `application_type: 'native'` to the client metadata document. The affected versions are v2.1.80 through at least v2.1.150; the fix is server-side and does not require a specific npm version upgrade, though re-authenticating after the server fix is necessary.

Claude Code's concurrent tool execution (parallel tool calls) triggers Anthropic API Error 400 with 'tool_use ids must be unique' or 'tool use concurrency issues' messages that corrupt the conversation and require /rewind recovery. The root cause involves multiple mechanisms: PostToolUse/PostEdit hook stdout being mislabeled as user messages in the API payload, .claude/ide/ lock file corruption, and tool_use ID collisions when MCP servers or large file processing trigger parallel tool calls. Anthropic staff (bcherny) acknowledged multiple root causes and closed the issue as fixed in v2.0.17–v2.0.19. Workarounds include disabling concurrent tool execution via CLAUDE.md instructions, removing hook processing, and deleting IDE lock files. Affects VS Code extension users most severely because /rewind is unavailable outside the CLI.

MCP servers fail to start when using Node version managers (NVM, FNM, Volta, n, mise, proto) because GUI applications like Claude Desktop and Cursor use child_process.spawn() with shell:false instead of a shell. NVM's shell functions (loaded via ~/.bashrc/~/.zshrc) are never available to spawned subprocesses, causing 'npx' to resolve to the wrong Node binary or fail with ENOENT/-32000. The MCP TypeScript SDK's stdio.ts explicitly uses spawn() without shell integration (confirmed in source), making this a fundamental architectural limitation affecting ALL MCP clients. Five distinct, battle-tested workarounds exist — from one-command wrapper scripts (66 reactions on GitHub #64) to absolute-path configuration and version-manager migration.

A native-layer bug in Anthropic's custom Bun fork causes Claude Code to permanently invalidate prompt cache across conversation turns. The root cause, identified through MITM proxy capture and Ghidra reverse engineering (jmarianski, Issue #40524), is a sentinel replacement mechanism that rewrites the billing attribution header (cch=00000) into historical tool results, breaking the cache prefix and forcing full cache rewrites on every subsequent turn. Symptoms include: 200K-300K cache_create token spikes per turn, weekly quotas exhausted in 1-2 hours instead of 5+, and API billing invoices 40-100% above key-level usage. Affected versions: v2.1.69 through v2.1.90 (v2.1.82 and v2.1.88 were never published to npm). A partial tool-schema-bytes fix landed in v2.1.89 (changelog commit 2d5c1ba). Multiple workarounds exist: set CLAUDE_CODE_ATTRIBUTION_HEADER=false (dead-simple, non-developer), downgrade to v2.1.68 (last known-good), or use npx instead of the binary. The issue was closed as completed on Apr 4, 2026. Latest Claude Code version is v2.1.173 (npm, verified 2026-06-11). For heavy skill/hook users, residual cache issues may still occur even on latest — use ANTHROPIC_LOG=debug to monitor.

Claude Code v2.1.120 (April 24, 2026) introduced a regression that crashes EVERY interactive session resume with 'ERROR g9H is not a function. (In g9H(K), g9H is undefined)'. The crash occurs in the REPL component's mount effect: when `FXK({enabled: false, ...})` is called, the returned object lacks `onSessionRestored`, but the mount effect unconditionally invokes `g9H(K)` whenever the resumed session has messages. Anthropic staff member wolffiex acknowledged the issue within hours, rolled back the auto-update pointer from v2.1.120 to v2.1.119, and closed the issue as completed. IMPORTANT: v2.1.120 STILL EXISTS on npm (April 2026–present) — the fix was auto-updater-side only, not a new npm release. Users who install via npm without version pinning may still get the broken version. The workaround is to use print mode (`claude -p --resume <id> '...'`) or pin to v2.1.119 / v2.1.121+. Latest Claude Code as of June 2026 is v2.1.177.

The MCP TypeScript SDK v1.17.5 and earlier has a hard dependency on Zod v3 (`^3.23.8`) and uses internal Zod methods (`_parse`, `_def`) that were removed or changed in Zod v4. When any downstream project (Claude Desktop, Cursor, VS Code, Cline, or any MCP client using the TypeScript SDK) upgrades to Zod v4, all MCP server tool calls fail with JSON-RPC error code -32603: `_parse is not a function` or `null is not an object (evaluating 'F._def')`. This breaks every MCP server that imports Zod v4, affecting the entire MCP ecosystem. MCP TypeScript SDK maintainer felixweinberger confirmed the fix: v1.23.0-beta.0 (released November 21, 2025) added backwards-compatible Zod v4 support by switching the dependency to `^3.25 || ^4.0`. The stable fix ships in v1.23.1+. Users should upgrade their MCP SDK dependency to `>=1.23.1`. The latest MCP SDK as of June 2026 is v1.29.0.

When Claude Code running in VS Code (v2.1.83 through v2.1.85) encounters a task that takes more than 60 seconds, the UI displays a red spinner with the text "Not responding · try stopping" but provides NO actionable way to stop, cancel, or recover. The session becomes a dead end — users must force-quit VS Code and lose all progress, including completed tasks upstream of the stall. This occurs when any external operation hangs beyond the backend heartbeat timeout. Anthropic staff member qing-ant confirmed the timeout was too aggressive and deployed a fix in v2.1.86 (March 27, 2026), same day the issue was closed. Affected users reported the issue across all Claude Code modes (Ask, Plan, Code) on macOS, with 54 reactions and 73 comments confirming widespread impact. The latest Claude Code as of June 2026 is v2.1.177.