[{"data":1,"prerenderedAt":2513},["ShallowReactive",2],{"blog-post-hermes-agent-error-400-8-causes-fixes":3,"related-posts-hermes-agent-error-400-8-causes-fixes":977},{"id":4,"title":5,"author":6,"body":10,"category":956,"date":957,"description":958,"extension":959,"featured":960,"image":961,"imageHeight":962,"imageWidth":962,"meta":963,"navigation":161,"path":964,"readingTime":965,"seo":966,"seoTitle":967,"stem":968,"tags":969,"updatedDate":957,"__hash__":976},"blog/blog/hermes-agent-error-400-8-causes-fixes.md","Hermes Agent Error 400: 8 Causes and Copy-Paste Fixes (2026)",{"name":7,"role":8,"avatar":9},"Shabnam Katoch","Growth Head","/img/avatars/shabnam-profile.jpeg",{"type":11,"value":12,"toc":938},"minimark",[13,20,28,31,34,43,46,51,58,64,69,105,132,137,189,192,196,201,206,210,255,258,262,275,280,284,344,350,354,360,369,374,378,413,416,420,425,429,458,465,470,487,491,496,501,505,543,551,555,561,574,583,587,627,639,643,656,668,672,709,712,718,722,725,730,748,753,772,775,780,797,800,808,814,817,820,841,845,850,862,866,892,896,913,917,920,924,934],[14,15,16],"p",{},[17,18,19],"strong",{},"\"Non-retryable client error (HTTP 400). Aborting.\" Six words that tell you nothing about what's actually wrong. Here are the eight real causes, sourced from GitHub issues, with a copy-paste fix for each.",[14,21,22,23,27],{},"A user filed GitHub issue #26161 three days ago. Hermes v0.13.0. Gemini provider. First message: \"hello.\" Response: ",[24,25,26],"code",{},"GeminiAPIError [HTTP 400] Bad Request",".",[14,29,30],{},"The model existed. The API key worked. Curl to the endpoint returned a valid response. But Hermes returned 400 on every attempt.",[14,32,33],{},"The error message gave zero diagnostic information. Just \"HTTP 400\" and \"Bad Request.\" The user had to upload debug logs, agent logs, and gateway logs before anyone could help.",[14,35,36,37,42],{},"This is the most common runtime error in ",[38,39,41],"a",{"href":40},"/compare/hermes","Hermes Agent",". The official FAQ confirms it: \"Setup completes fine, but the first chat attempt fails with HTTP 400.\" And the error message is always the same regardless of cause.",[14,44,45],{},"Here are the eight real causes of Hermes Agent error 400, ranked by how often they appear in GitHub issues, with copy-paste fixes for each.",[47,48,50],"h2",{"id":49},"cause-1-model-name-mismatch-the-1-cause","Cause 1: Model name mismatch (the #1 cause)",[14,52,53],{},[54,55],"img",{"alt":56,"src":57},"Cause 1 Model Name Mismatch: what you typed (claude-sonnet-4, gpt-5, gemini-flash) versus what the provider expects (claude-sonnet-4-6-20260514, gpt-5.5, gemini-3.5-flash) — a one-character difference returns HTTP 400","/img/blog/hermes-400-cause1-model-mismatch.jpg",[14,59,60,63],{},[17,61,62],{},"What happens:"," The model ID in your config doesn't match what the provider expects. Hermes sends the request. The provider says \"I don't know that model.\" Returns 400.",[14,65,66],{},[17,67,68],{},"How to diagnose:",[70,71,76],"pre",{"className":72,"code":73,"language":74,"meta":75,"style":75},"language-bash shiki shiki-themes github-light","hermes config show | head -20\n","bash","",[24,77,78],{"__ignoreMap":75},[79,80,83,87,91,94,98,101],"span",{"class":81,"line":82},"line",1,[79,84,86],{"class":85},"s7eDp","hermes",[79,88,90],{"class":89},"sYBdl"," config",[79,92,93],{"class":89}," show",[79,95,97],{"class":96},"sD7c4"," |",[79,99,100],{"class":85}," head",[79,102,104],{"class":103},"sYu0t"," -20\n",[14,106,107,108,111,112,115,116,119,120,115,123,119,126,115,129,27],{},"Check the ",[24,109,110],{},"model.id"," field. Common mismatches: ",[24,113,114],{},"claude-sonnet-4"," instead of ",[24,117,118],{},"claude-sonnet-4-20260514",", ",[24,121,122],{},"gpt-5",[24,124,125],{},"gpt-5.5",[24,127,128],{},"gemini-flash",[24,130,131],{},"gemini-3.5-flash",[14,133,134],{},[17,135,136],{},"Copy-paste fix:",[70,138,140],{"className":72,"code":139,"language":74,"meta":75,"style":75},"# Re-run model selection\nhermes model\n\n# Or test with a known-good model\nhermes chat -q \"hello\" --model anthropic/claude-sonnet-4-6-20260514\n",[24,141,142,148,156,163,169],{"__ignoreMap":75},[79,143,144],{"class":81,"line":82},[79,145,147],{"class":146},"sAwPA","# Re-run model selection\n",[79,149,151,153],{"class":81,"line":150},2,[79,152,86],{"class":85},[79,154,155],{"class":89}," model\n",[79,157,159],{"class":81,"line":158},3,[79,160,162],{"emptyLinePlaceholder":161},true,"\n",[79,164,166],{"class":81,"line":165},4,[79,167,168],{"class":146},"# Or test with a known-good model\n",[79,170,172,174,177,180,183,186],{"class":81,"line":171},5,[79,173,86],{"class":85},[79,175,176],{"class":89}," chat",[79,178,179],{"class":103}," -q",[79,181,182],{"class":89}," \"hello\"",[79,184,185],{"class":103}," --model",[79,187,188],{"class":89}," anthropic/claude-sonnet-4-6-20260514\n",[14,190,191],{},"If the known-good model works, your original model ID was wrong. Check your provider's model list for the exact ID.",[47,193,195],{"id":194},"cause-2-tool-schema-incompatibility-with-openrouter","Cause 2: Tool schema incompatibility with OpenRouter",[14,197,198,200],{},[17,199,62],{}," Hermes sends 28 tool definitions by default. Some models on OpenRouter can't parse all 28 schemas. Every API call returns 400 regardless of the model you select. GitHub issue #13927: all three tested models (Claude Sonnet, GPT-4o Mini, Gemini Flash) failed with the same 400.",[14,202,203,205],{},[17,204,68],{}," If EVERY model fails with 400 on OpenRouter but the same API key works via curl, it's tool schemas.",[14,207,208],{},[17,209,136],{},[70,211,213],{"className":72,"code":212,"language":74,"meta":75,"style":75},"# Disable tools temporarily to confirm the diagnosis\nhermes chat -q \"hello\" --no-tools\n\n# If that works, the issue is tool schemas.\n# Update Hermes to the latest version (schema fixes ship frequently)\nhermes update\n",[24,214,215,220,233,237,242,247],{"__ignoreMap":75},[79,216,217],{"class":81,"line":82},[79,218,219],{"class":146},"# Disable tools temporarily to confirm the diagnosis\n",[79,221,222,224,226,228,230],{"class":81,"line":150},[79,223,86],{"class":85},[79,225,176],{"class":89},[79,227,179],{"class":103},[79,229,182],{"class":89},[79,231,232],{"class":103}," --no-tools\n",[79,234,235],{"class":81,"line":158},[79,236,162],{"emptyLinePlaceholder":161},[79,238,239],{"class":81,"line":165},[79,240,241],{"class":146},"# If that works, the issue is tool schemas.\n",[79,243,244],{"class":81,"line":171},[79,245,246],{"class":146},"# Update Hermes to the latest version (schema fixes ship frequently)\n",[79,248,250,252],{"class":81,"line":249},6,[79,251,86],{"class":85},[79,253,254],{"class":89}," update\n",[14,256,257],{},"If updating doesn't fix it, reduce the number of enabled tools. 28 default tools is aggressive. Disable tools you don't use in your config.",[47,259,261],{"id":260},"cause-3-dual-authentication-headers-on-gemini","Cause 3: Dual authentication headers on Gemini",[14,263,264,266,267,270,271,274],{},[17,265,62],{}," Hermes's gemini provider injects an ",[24,268,269],{},"x-goog-api-key"," header. Simultaneously, the OpenAI Python SDK injects an ",[24,272,273],{},"Authorization: Bearer"," header. Google's API rejects requests with both headers. GitHub issue #7893 documents this exactly.",[14,276,277,279],{},[17,278,68],{}," The error message includes \"Multiple authentication credentials received.\"",[14,281,282],{},[17,283,136],{},[70,285,287],{"className":72,"code":286,"language":74,"meta":75,"style":75},"# Generate a standard Google Cloud API key (starts with AIza...)\n# NOT a Vertex AI key (starts with AQ.Ab8...)\n\n# Add to your env\necho 'GEMINI_API_KEY=AIzaSy...' >> ~/.hermes/.env\n\n# Verify\nhermes chat -q \"hello\"\n",[24,288,289,294,299,303,308,322,326,332],{"__ignoreMap":75},[79,290,291],{"class":81,"line":82},[79,292,293],{"class":146},"# Generate a standard Google Cloud API key (starts with AIza...)\n",[79,295,296],{"class":81,"line":150},[79,297,298],{"class":146},"# NOT a Vertex AI key (starts with AQ.Ab8...)\n",[79,300,301],{"class":81,"line":158},[79,302,162],{"emptyLinePlaceholder":161},[79,304,305],{"class":81,"line":165},[79,306,307],{"class":146},"# Add to your env\n",[79,309,310,313,316,319],{"class":81,"line":171},[79,311,312],{"class":103},"echo",[79,314,315],{"class":89}," 'GEMINI_API_KEY=AIzaSy...'",[79,317,318],{"class":96}," >>",[79,320,321],{"class":89}," ~/.hermes/.env\n",[79,323,324],{"class":81,"line":249},[79,325,162],{"emptyLinePlaceholder":161},[79,327,329],{"class":81,"line":328},7,[79,330,331],{"class":146},"# Verify\n",[79,333,335,337,339,341],{"class":81,"line":334},8,[79,336,86],{"class":85},[79,338,176],{"class":89},[79,340,179],{"class":103},[79,342,343],{"class":89}," \"hello\"\n",[14,345,346,347,27],{},"The Vertex AI key format triggers the dual-header bug. Use a standard Google Cloud API key. It must start with ",[24,348,349],{},"AIza",[47,351,353],{"id":352},"cause-4-missing-reasoning_content-for-thinking-models","Cause 4: Missing reasoning_content for thinking models",[14,355,356],{},[54,357],{"alt":358,"src":359},"Why the second message fails: message 1 succeeds, message 2 fails because the reasoning_content field is dropped from the assistant turn, and updating Hermes produces a fixed version that passes the field back","/img/blog/hermes-400-cause4-reasoning-content.jpg",[14,361,362,364,365,368],{},[17,363,62],{}," Models with thinking mode (Kimi K2.6, DeepSeek V4 Flash) return ",[24,366,367],{},"reasoning_content"," in their responses. Hermes doesn't pass it back in subsequent messages. The provider rejects the request because the conversation history is malformed. GitHub issues #13848 (Kimi) and #15717 (DeepSeek) document this.",[14,370,371,373],{},[17,372,68],{}," The 400 happens after the SECOND message, not the first. First message works. Second message fails with \"reasoning_content is missing.\"",[14,375,376],{},[17,377,136],{},[70,379,381],{"className":72,"code":380,"language":74,"meta":75,"style":75},"# Update to latest Hermes (reasoning_content handling was fixed in recent versions)\nhermes update\n\n# If still failing, disable thinking mode for the provider.\n# In ~/.hermes/config.yaml, add under your model:\n#   thinking: false\n",[24,382,383,388,394,398,403,408],{"__ignoreMap":75},[79,384,385],{"class":81,"line":82},[79,386,387],{"class":146},"# Update to latest Hermes (reasoning_content handling was fixed in recent versions)\n",[79,389,390,392],{"class":81,"line":150},[79,391,86],{"class":85},[79,393,254],{"class":89},[79,395,396],{"class":81,"line":158},[79,397,162],{"emptyLinePlaceholder":161},[79,399,400],{"class":81,"line":165},[79,401,402],{"class":146},"# If still failing, disable thinking mode for the provider.\n",[79,404,405],{"class":81,"line":171},[79,406,407],{"class":146},"# In ~/.hermes/config.yaml, add under your model:\n",[79,409,410],{"class":81,"line":249},[79,411,412],{"class":146},"#   thinking: false\n",[14,414,415],{},"This is a known issue with Kimi and DeepSeek providers. The fix ships in Hermes updates. If you're on an older version, updating resolves it.",[47,417,419],{"id":418},"cause-5-insufficient-openrouter-credits","Cause 5: Insufficient OpenRouter credits",[14,421,422,424],{},[17,423,62],{}," Your OpenRouter API key is valid but has no credits. OpenRouter returns 400 instead of a more helpful error code.",[14,426,427],{},[17,428,68],{},[70,430,432],{"className":72,"code":431,"language":74,"meta":75,"style":75},"# Test your key directly\ncurl https://openrouter.ai/api/v1/auth/key \\\n  -H \"Authorization: Bearer sk-or-your-key-here\"\n",[24,433,434,439,450],{"__ignoreMap":75},[79,435,436],{"class":81,"line":82},[79,437,438],{"class":146},"# Test your key directly\n",[79,440,441,444,447],{"class":81,"line":150},[79,442,443],{"class":85},"curl",[79,445,446],{"class":89}," https://openrouter.ai/api/v1/auth/key",[79,448,449],{"class":103}," \\\n",[79,451,452,455],{"class":81,"line":158},[79,453,454],{"class":103},"  -H",[79,456,457],{"class":89}," \"Authorization: Bearer sk-or-your-key-here\"\n",[14,459,460,461,464],{},"If the response shows ",[24,462,463],{},"\"limit_remaining\": 0"," or similar, you need credits.",[14,466,467,469],{},[17,468,136],{}," Add credits on OpenRouter's dashboard. If using the free tier, some models require a paid plan. Switch to a model that works on free tier, or add $5 in credits.",[14,471,472,473,477,478,482,483,27],{},"If you'd rather not debug provider-specific error codes, ",[38,474,476],{"href":475},"/openclaw-alternative","BetterClaw handles provider errors at the platform level",". You never see raw HTTP status codes. 28+ providers via BYOK. Smart error handling included. ",[38,479,481],{"href":480},"/free-plan","Free plan"," with every feature. ",[38,484,486],{"href":485},"/pricing","$19/month per agent on Pro",[47,488,490],{"id":489},"cause-6-oversized-request-payload","Cause 6: Oversized request payload",[14,492,493,495],{},[17,494,62],{}," Your conversation history, system prompt, and tool definitions exceed the provider's request size limit. The provider returns 400 because the payload is too large.",[14,497,498,500],{},[17,499,68],{}," The 400 starts appearing mid-conversation, not at the start. Earlier messages worked fine. The conversation grew too long.",[14,502,503],{},[17,504,136],{},[70,506,508],{"className":72,"code":507,"language":74,"meta":75,"style":75},"# Start a new session (clears conversation history)\nhermes chat --new\n\n# Or reduce context window in config.\n# In ~/.hermes/config.yaml:\n#   context_window: 32768\n",[24,509,510,515,524,528,533,538],{"__ignoreMap":75},[79,511,512],{"class":81,"line":82},[79,513,514],{"class":146},"# Start a new session (clears conversation history)\n",[79,516,517,519,521],{"class":81,"line":150},[79,518,86],{"class":85},[79,520,176],{"class":89},[79,522,523],{"class":103}," --new\n",[79,525,526],{"class":81,"line":158},[79,527,162],{"emptyLinePlaceholder":161},[79,529,530],{"class":81,"line":165},[79,531,532],{"class":146},"# Or reduce context window in config.\n",[79,534,535],{"class":81,"line":171},[79,536,537],{"class":146},"# In ~/.hermes/config.yaml:\n",[79,539,540],{"class":81,"line":249},[79,541,542],{"class":146},"#   context_window: 32768\n",[14,544,545,546,550],{},"For long-running agents, implement session management. Our ",[38,547,549],{"href":548},"/blog/ai-agent-context-window-explained","context window management guide"," covers how to prevent payload bloat.",[47,552,554],{"id":553},"cause-7-wrong-gemini-endpoint-version","Cause 7: Wrong Gemini endpoint version",[14,556,557],{},[54,558],{"alt":559,"src":560},"A request routing to the wrong Gemini endpoint: preview models rejected on /v1 but accepted on /v1beta — preview models need the v1beta endpoint","/img/blog/hermes-400-cause7-endpoint-version.jpg",[14,562,563,565,566,569,570,573],{},[17,564,62],{}," Hermes sends requests to ",[24,567,568],{},"/v1"," but some Gemini models require ",[24,571,572],{},"/v1beta",". Or vice versa. The endpoint doesn't recognize the model and returns 400.",[14,575,576,578,579,582],{},[17,577,68],{}," The error includes ",[24,580,581],{},"Error 400 (Bad Request)!!1"," (the HTML error page from Google, not a JSON error). This HTML response is distinctive.",[14,584,585],{},[17,586,136],{},[70,588,590],{"className":72,"code":589,"language":74,"meta":75,"style":75},"# In ~/.hermes/.env, try switching the endpoint\nGEMINI_API_BASE=https://generativelanguage.googleapis.com/v1beta/openai\n\n# Or if you were using v1beta, try v1:\nGEMINI_API_BASE=https://generativelanguage.googleapis.com/v1/openai\n",[24,591,592,597,609,613,618],{"__ignoreMap":75},[79,593,594],{"class":81,"line":82},[79,595,596],{"class":146},"# In ~/.hermes/.env, try switching the endpoint\n",[79,598,599,603,606],{"class":81,"line":150},[79,600,602],{"class":601},"sgsFI","GEMINI_API_BASE",[79,604,605],{"class":96},"=",[79,607,608],{"class":89},"https://generativelanguage.googleapis.com/v1beta/openai\n",[79,610,611],{"class":81,"line":158},[79,612,162],{"emptyLinePlaceholder":161},[79,614,615],{"class":81,"line":165},[79,616,617],{"class":146},"# Or if you were using v1beta, try v1:\n",[79,619,620,622,624],{"class":81,"line":171},[79,621,602],{"class":601},[79,623,605],{"class":96},[79,625,626],{"class":89},"https://generativelanguage.googleapis.com/v1/openai\n",[14,628,629,630,633,634,636,637,27],{},"The correct endpoint depends on the model. Preview models (like ",[24,631,632],{},"gemini-3-flash-preview",") typically need ",[24,635,572],{},". Stable models work on ",[24,638,568],{},[47,640,642],{"id":641},"cause-8-model-id-format-mismatch-dots-vs-hyphens","Cause 8: Model ID format mismatch (dots vs hyphens)",[14,644,645,647,648,651,652,655],{},[17,646,62],{}," Some providers use dots in model IDs (",[24,649,650],{},"minimax-m2.5-free","). Hermes's config parser converts dots to hyphens (",[24,653,654],{},"minimax-m2-5-free","). The provider doesn't recognize the hyphenated version. GitHub issue #7710 documents this with OpenCode Zen.",[14,657,658,660,661,664,665,667],{},[17,659,68],{}," Run ",[24,662,663],{},"hermes config show"," and compare the ",[24,666,110],{}," against the provider's documentation. If dots were converted to hyphens, that's the cause.",[14,669,670],{},[17,671,136],{},[70,673,677],{"className":674,"code":675,"language":676,"meta":75,"style":75},"language-yaml shiki shiki-themes github-light","# Edit config directly to use the exact model ID.\n# In ~/.hermes/config.yaml, wrap the model ID in quotes:\nmodel:\n  id: \"minimax-m2.5-free\"\n","yaml",[24,678,679,684,689,698],{"__ignoreMap":75},[79,680,681],{"class":81,"line":82},[79,682,683],{"class":146},"# Edit config directly to use the exact model ID.\n",[79,685,686],{"class":81,"line":150},[79,687,688],{"class":146},"# In ~/.hermes/config.yaml, wrap the model ID in quotes:\n",[79,690,691,695],{"class":81,"line":158},[79,692,694],{"class":693},"shJU0","model",[79,696,697],{"class":601},":\n",[79,699,700,703,706],{"class":81,"line":165},[79,701,702],{"class":693},"  id",[79,704,705],{"class":601},": ",[79,707,708],{"class":89},"\"minimax-m2.5-free\"\n",[14,710,711],{},"Quoting the model ID preserves the dots. Without quotes, YAML interprets dots as nested keys.",[14,713,714],{},[54,715],{"alt":716,"src":717},"Hermes Error 400 quick fix reference table: 1 model mismatch → hermes model re-select, 2 tool schema → hermes update or --no-tools, 3 dual auth Gemini → use AIza key not Vertex, 4 missing reasoning → hermes update, 5 no credits → add OpenRouter credits, 6 oversized payload → hermes chat --new, 7 wrong endpoint → switch v1/v1beta, 8 dots vs hyphens → quote model ID in YAML","/img/blog/hermes-400-quick-fix-reference.jpg",[47,719,721],{"id":720},"the-diagnostic-sequence-run-this-first","The diagnostic sequence (run this first)",[14,723,724],{},"Before trying all eight fixes, run this three-step diagnostic.",[14,726,727],{},[17,728,729],{},"Step 1: Verify your model and provider.",[70,731,732],{"className":72,"code":73,"language":74,"meta":75,"style":75},[24,733,734],{"__ignoreMap":75},[79,735,736,738,740,742,744,746],{"class":81,"line":82},[79,737,86],{"class":85},[79,739,90],{"class":89},[79,741,93],{"class":89},[79,743,97],{"class":96},[79,745,100],{"class":85},[79,747,104],{"class":103},[14,749,750],{},[17,751,752],{},"Step 2: Test with a known-good model.",[70,754,756],{"className":72,"code":755,"language":74,"meta":75,"style":75},"hermes chat -q \"hello\" --model anthropic/claude-sonnet-4-6-20260514\n",[24,757,758],{"__ignoreMap":75},[79,759,760,762,764,766,768,770],{"class":81,"line":82},[79,761,86],{"class":85},[79,763,176],{"class":89},[79,765,179],{"class":103},[79,767,182],{"class":89},[79,769,185],{"class":103},[79,771,188],{"class":89},[14,773,774],{},"If this works, the problem is model-specific (Causes 1, 4, 7, 8). If this also fails, the problem is provider-wide (Causes 2, 3, 5, 6).",[14,776,777],{},[17,778,779],{},"Step 3: Test without tools.",[70,781,783],{"className":72,"code":782,"language":74,"meta":75,"style":75},"hermes chat -q \"hello\" --no-tools\n",[24,784,785],{"__ignoreMap":75},[79,786,787,789,791,793,795],{"class":81,"line":82},[79,788,86],{"class":85},[79,790,176],{"class":89},[79,792,179],{"class":103},[79,794,182],{"class":89},[79,796,232],{"class":103},[14,798,799],{},"If this works, the problem is tool schemas (Cause 2). If it still fails, the problem is authentication or payload (Causes 3, 5, 6).",[14,801,802,803,807],{},"This sequence narrows eight possible causes to two in about 30 seconds. Not sure which error you're staring at? Paste it into our ",[38,804,806],{"href":805},"/tools/agent-error-decoder","agent error decoder"," to match the message to a cause and fix.",[14,809,810],{},[54,811],{"alt":812,"src":813},"Diagnostic flow: Step 1 check config, Step 2 test a known-good model, Step 3 run with no tools — at each step a pass narrows the cause and a clean run through all three means the issue is resolved","/img/blog/hermes-400-diagnostic-flow.jpg",[14,815,816],{},"The honest truth about Hermes error 400: the error message is useless. \"HTTP 400 Bad Request\" tells you nothing about which of eight different causes is responsible. Every fix above was sourced from real GitHub issues where users spent hours diagnosing problems that should take seconds.",[14,818,819],{},"This is the core tradeoff of self-hosted agent frameworks. Maximum control. Maximum debugging.",[14,821,822,828,829,833,834,836,837,840],{},[38,823,827],{"href":824,"rel":825},"https://app.betterclaw.io/sign-in",[826],"nofollow","Give BetterClaw a look"," if you'd rather build agents than debug HTTP status codes. Provider errors are handled at the platform level. 200+ ",[38,830,832],{"href":831},"/skills","verified skills",". 25+ OAuth integrations. ",[38,835,481],{"href":480}," with 1 agent and every feature. ",[38,838,839],{"href":485},"$19/month per agent for Pro",". We handle the provider compatibility. You handle the agent logic.",[47,842,844],{"id":843},"frequently-asked-questions","Frequently Asked Questions",[846,847,849],"h3",{"id":848},"what-causes-hermes-agent-error-400","What causes Hermes Agent error 400?",[14,851,852,853,855,856,858,859,861],{},"Hermes error 400 means the API provider rejected the request as malformed. The eight most common causes: model name mismatch (most frequent), tool schema incompatibility with OpenRouter, dual authentication headers on Gemini, missing ",[24,854,367],{}," for thinking models (Kimi, DeepSeek), insufficient OpenRouter credits, oversized request payload, wrong Gemini endpoint version (",[24,857,568],{}," vs ",[24,860,572],{},"), and model ID format mismatch (dots vs hyphens in YAML). The error message is always the same regardless of cause.",[846,863,865],{"id":864},"how-do-i-fix-hermes-error-400-with-gemini","How do I fix Hermes error 400 with Gemini?",[14,867,868,869,871,872,874,875,878,879,881,882,884,885,887,888,891],{},"Gemini-specific 400 errors have two common causes. First: dual authentication headers. Hermes injects both ",[24,870,269],{}," and ",[24,873,273],{}," headers. Fix: use a standard Google Cloud API key starting with ",[24,876,877],{},"AIza..."," (not a Vertex AI key). Second: wrong endpoint version. Preview models need ",[24,880,572],{},", stable models need ",[24,883,568],{},". Set ",[24,886,602],{}," in your ",[24,889,890],{},"~/.hermes/.env"," to the correct endpoint.",[846,893,895],{"id":894},"why-does-hermes-error-400-happen-on-the-second-message-but-not-the-first","Why does Hermes error 400 happen on the second message but not the first?",[14,897,898,899,901,902,904,905,908,909,912],{},"Two causes trigger 400 on the second message: missing ",[24,900,367],{}," (thinking models like Kimi K2.6 and DeepSeek V4 Flash return reasoning tokens that Hermes doesn't pass back in subsequent turns) and oversized payload (conversation history grows too large after the first exchange). Fix ",[24,903,367],{}," with ",[24,906,907],{},"hermes update",". Fix payload with ",[24,910,911],{},"hermes chat --new"," to start a fresh session.",[846,914,916],{"id":915},"does-hermes-error-400-mean-my-api-key-is-wrong","Does Hermes error 400 mean my API key is wrong?",[14,918,919],{},"Usually not. Error 400 means \"bad request,\" not \"bad credentials\" (that would be 401). In most cases, the API key is valid but the request is malformed due to model name mismatches, incompatible tool schemas, or provider-specific format requirements. Test your key with curl to confirm it works independently, then follow the three-step diagnostic sequence in this guide.",[846,921,923],{"id":922},"how-do-i-avoid-hermes-error-400-entirely","How do I avoid Hermes error 400 entirely?",[14,925,926,927,929,930,933],{},"Keep Hermes updated (",[24,928,907],{},"). Use exact model IDs from your provider's documentation. Limit enabled tools to what you actually need. Use standard API keys (not Vertex AI keys for Gemini). Monitor conversation length and start new sessions before hitting payload limits. Or use a managed platform like BetterClaw (",[38,931,932],{"href":485},"$0 free, $19/month Pro",") where provider errors are handled at the platform level and you never see raw HTTP status codes.",[935,936,937],"style",{},"html pre.shiki code .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html pre.shiki code .sD7c4, html code.shiki .sD7c4{--shiki-default:#D73A49}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .shJU0, html code.shiki .shJU0{--shiki-default:#22863A}",{"title":75,"searchDepth":150,"depth":150,"links":939},[940,941,942,943,944,945,946,947,948,949],{"id":49,"depth":150,"text":50},{"id":194,"depth":150,"text":195},{"id":260,"depth":150,"text":261},{"id":352,"depth":150,"text":353},{"id":418,"depth":150,"text":419},{"id":489,"depth":150,"text":490},{"id":553,"depth":150,"text":554},{"id":641,"depth":150,"text":642},{"id":720,"depth":150,"text":721},{"id":843,"depth":150,"text":844,"children":950},[951,952,953,954,955],{"id":848,"depth":158,"text":849},{"id":864,"depth":158,"text":865},{"id":894,"depth":158,"text":895},{"id":915,"depth":158,"text":916},{"id":922,"depth":158,"text":923},"Troubleshooting","2026-06-22","Hermes Agent HTTP 400 has 8 different causes. Model mismatch, tool schemas, Gemini dual auth, and 5 more. Copy-paste fix for each.","md",false,"/img/blog/hermes-400-8-causes-8-fixes.jpg",null,{},"/blog/hermes-agent-error-400-8-causes-fixes","10 min read",{"title":5,"description":958},"Hermes Error 400: 8 Causes and Fixes (2026)","blog/hermes-agent-error-400-8-causes-fixes",[970,971,972,973,974,975],"hermes error 400","hermes agent bad request","hermes 400 fix","hermes agent api error","hermes http 400","openclaw error 400","8dA2kSRV1qJ3FlUvtFAAQlgqMOkmIVzx62hsvJBMBXg",[978,1434,1930],{"id":979,"title":980,"author":981,"body":982,"category":956,"date":1416,"description":1417,"extension":959,"featured":960,"image":1418,"imageHeight":962,"imageWidth":962,"meta":1419,"navigation":161,"path":1420,"readingTime":1421,"seo":1422,"seoTitle":1423,"stem":1424,"tags":1425,"updatedDate":1416,"__hash__":1433},"blog/blog/ai-agent-slow-latency-fix.md","Why Is My AI Agent So Slow? Diagnosing Latency Step by Step",{"name":7,"role":8,"avatar":9},{"type":11,"value":983,"toc":1388},[984,987,990,993,996,999,1002,1006,1009,1012,1018,1022,1025,1028,1034,1040,1046,1049,1052,1056,1059,1062,1065,1068,1071,1074,1078,1081,1085,1091,1101,1107,1113,1117,1120,1123,1126,1129,1132,1135,1141,1147,1153,1159,1162,1166,1169,1172,1179,1182,1185,1191,1197,1203,1209,1213,1216,1219,1222,1225,1228,1232,1235,1238,1241,1245,1248,1254,1260,1266,1272,1278,1284,1287,1290,1294,1297,1303,1314,1320,1331,1334,1337,1351,1353,1357,1360,1364,1367,1371,1374,1378,1381,1385],[14,985,986],{},"We had an agent handling email triage. It read new emails, classified urgency, drafted responses for low-priority items, and flagged high-priority ones for human review.",[14,988,989],{},"In testing, it was fast. Sub-two-second responses. We were thrilled.",[14,991,992],{},"In production, it took 15 seconds per email. Sometimes 20. Users started complaining within the first hour.",[14,994,995],{},"My first instinct: the model is too slow, let's switch to something faster. So we swapped Claude Sonnet for GPT-5 Nano. Barely any improvement. Maybe half a second shaved off.",[14,997,998],{},"That's when it hit me. The model wasn't the bottleneck. The model was doing its job in under a second. Everything else around it was eating the other 14 seconds.",[14,1000,1001],{},"If your AI agent is slow, the model is almost never the real problem. The real problem lives in one of five places. Here's how to find it.",[47,1003,1005],{"id":1004},"the-five-latency-layers-debug-in-this-order","The five latency layers (debug in this order)",[14,1007,1008],{},"Most people start debugging agent latency by looking at model benchmarks. \"Maybe I need a faster LLM.\" That's like diagnosing a slow website by replacing the database when the real problem is unoptimized SQL queries hitting the database 47 times per page load.",[14,1010,1011],{},"Agent latency has five layers. They compound multiplicatively, not additively. A problem at layer 3 makes layer 4 worse, which makes layer 5 catastrophic.",[14,1013,1014],{},[54,1015],{"alt":1016,"src":1017},"The Five Latency Layers of an AI Agent, stacked to debug top to bottom without skipping: Layer 1 model speed (TTFT plus tok/s, most people blame this but it's rarely the real issue), Layer 2 context window size (every token in context costs processing time on every request), Layer 3 tool execution (external API calls, unmeasured and often the biggest offender), Layer 4 network plus API routing (geography adds up across 8-12 API calls per task), and Layer 5 multi-step compounding (every step multiplies all previous layers, the real killer). A problem at Layer 3 makes Layer 4 worse, and Layer 4 makes Layer 5 catastrophic","/img/blog/ai-agent-latency-five-layers.jpg",[47,1019,1021],{"id":1020},"layer-1-model-speed-the-one-everyone-checks-first","Layer 1: Model speed (the one everyone checks first)",[14,1023,1024],{},"Time to first token (TTFT) measures how long after you send a prompt the model starts generating. Per-token latency (tok/s) measures how fast it generates once it starts.",[14,1026,1027],{},"Here's where things stand in 2026:",[14,1029,1030,1033],{},[17,1031,1032],{},"Fastest TTFT:"," Claude Haiku 4.5 at around 597ms on medium prompts. Mistral Large and GPT-5.2 also hit sub-second consistently.",[14,1035,1036,1039],{},[17,1037,1038],{},"Fastest throughput:"," Gemini 2.5 Flash at 146-173 tokens per second. Mercury 2 by Inception hits 789 tok/s but with quality tradeoffs. Gemini 3.5 Flash reaches 284 tok/s.",[14,1041,1042,1045],{},[17,1043,1044],{},"Reasoning models are intentionally slow."," Models like o3, GPT-5, and Gemini Deep Think use chain-of-thought processing. They generate internal \"thinking\" tokens before the visible answer. TTFT can be 10-150 seconds. This isn't a bug. It's the architecture.",[14,1047,1048],{},"Here's the thing: for most agent workloads, model speed is not your bottleneck. A single LLM call takes about 800 milliseconds. If your agent is taking 15 seconds, the model used 800ms of that. You have 14.2 seconds of latency living somewhere else.",[14,1050,1051],{},"Before switching models, measure your actual model latency. Log the timestamp when you send the request and when the first token arrives. If it's under 2 seconds, your problem isn't the model.",[47,1053,1055],{"id":1054},"layer-2-context-window-bloat-the-silent-killer","Layer 2: Context window bloat (the silent killer)",[14,1057,1058],{},"This is where most agent latency actually lives. And it's invisible unless you're counting tokens.",[14,1060,1061],{},"Every time your agent makes a request, it sends the entire conversation context to the model. System prompt. Conversation history. Tool definitions. Previous tool results. Memory context. All of it.",[14,1063,1064],{},"The numbers are wild. Research from Agenteer found that a single Jira integration adds roughly 17,000 tokens just for tool definitions. Across a typical agent setup with multiple integrations, 134,000 tokens (67% of a 200K context window) get consumed by definitions before the agent starts working.",[14,1066,1067],{},"That's the equivalent of walking into a restaurant and reading a 500-page menu before you can order water.",[14,1069,1070],{},"More tokens means more processing time. A 2,000-token prompt processes in under a second. A 100,000-token prompt with tool definitions, conversation history, and previous results takes significantly longer. The model has to read and attend to every token before generating a response.",[14,1072,1073],{},"Your context window is RAM, not storage. Everything in it costs processing time on every single request.",[846,1075,1077],{"id":1076},"how-to-diagnose-it","How to diagnose it",[14,1079,1080],{},"Log your input token count for each request. If it's growing with every turn of the conversation, you have context bloat. If it starts high (above 20,000 tokens) even on the first turn, your tool definitions and system prompts are too heavy.",[846,1082,1084],{"id":1083},"how-to-fix-it","How to fix it",[14,1086,1087,1090],{},[17,1088,1089],{},"Don't load all tool definitions upfront."," Anthropic's own research showed that Opus 4's tool selection accuracy improved from 49% to 74% when the agent searched for relevant tools on demand instead of parsing all definitions at once. Fewer tools in context means faster processing and better accuracy.",[14,1092,1093,1096,1097,27],{},[17,1094,1095],{},"Summarize conversation history."," Instead of sending the full conversation, compress older turns into summaries. The Mem0 framework published 2026 benchmarks showing that a two-layer memory architecture (summarized context plus targeted retrieval) used 4x fewer tokens than full-context approaches while cutting latency by 91% and actually improving accuracy by 18.7 percentage points. This is the core of how ",[38,1098,1100],{"href":1099},"/blog/how-ai-agent-memory-works","AI agent memory works",[14,1102,1103,1106],{},[17,1104,1105],{},"Trim tool results aggressively."," A single MCP server call that returns a 50-field JSON blob when you only need 3 fields wastes thousands of tokens. Filter tool results before they enter context.",[14,1108,1109],{},[54,1110],{"alt":1111,"src":1112},"Context Bloat, the before and after. Before optimization: 119K tokens and 17-second p95 latency, made up of a 2K system prompt, 17K tool definitions, 40K conversation history and 60K tool results. After optimization: 11K tokens and 1.4-second p95 latency, made up of a 2K system prompt, 3K active tools only, 2K summarized history and 4K filtered results. A 91% latency reduction from context management alone, per Mem0 2026","/img/blog/ai-agent-latency-context-bloat-before-after.jpg",[47,1114,1116],{"id":1115},"layer-3-tool-execution-the-one-you-forgot-to-measure","Layer 3: Tool execution (the one you forgot to measure)",[14,1118,1119],{},"When your agent calls an external tool (send email, read CRM, query database, fetch webpage), the tool's execution time adds directly to the agent's response time. And most people never measure it.",[14,1121,1122],{},"A Gmail API call to fetch recent emails: 200-800ms. A HubSpot CRM lookup: 300-1,200ms. A web scraping call: 1-5 seconds. A database query on an unindexed table: could be anything from 50ms to 30 seconds.",[14,1124,1125],{},"If your agent makes 3 tool calls in sequence (which is common for multi-step tasks), and each takes an average of 1 second, that's 3 seconds of tool execution time before the model even starts thinking about the next step.",[846,1127,1077],{"id":1128},"how-to-diagnose-it-1",[14,1130,1131],{},"Wrap every tool call with timing logs. You'll often find that one specific tool is responsible for 60-80% of total tool execution time.",[846,1133,1084],{"id":1134},"how-to-fix-it-1",[14,1136,1137,1140],{},[17,1138,1139],{},"Parallelize where possible."," If your agent needs data from Gmail and HubSpot, fetch both simultaneously instead of sequentially. This cuts tool execution time in half for independent calls.",[14,1142,1143],{},[54,1144],{"alt":1145,"src":1146},"Parallelize Independent Tool Calls. Run sequentially, a Gmail fetch, a 900ms HubSpot lookup and an 800ms DB query total 2,300ms. Run in parallel, the same three calls (Gmail 600ms, HubSpot 900ms, DB 800ms) all run at once and total 900ms because the slowest one wins, 2.5x faster. If your agent needs Gmail and HubSpot, fetch both at once, not one then the other","/img/blog/ai-agent-latency-parallelize-tool-calls.jpg",[14,1148,1149,1152],{},[17,1150,1151],{},"Cache repeated lookups."," If your agent queries the same CRM record multiple times in one conversation, cache the first result. Semantic caching, as Redis LangCache demonstrated, can reduce redundant API calls dramatically.",[14,1154,1155,1158],{},[17,1156,1157],{},"Set timeouts."," A tool call that takes 30 seconds because of an external API issue shouldn't freeze your entire agent. Set aggressive timeouts (3-5 seconds) and have fallback behavior.",[14,1160,1161],{},"This is one of the areas where managed agent platforms have an advantage over self-hosted setups. On BetterClaw, integrations are pre-optimized with connection pooling, caching, and timeout handling built in. When you self-host, you're building all of that yourself.",[47,1163,1165],{"id":1164},"layer-4-network-and-api-routing","Layer 4: Network and API routing",[14,1167,1168],{},"If your agent is on a VPS in Frankfurt and your users are in San Francisco, every API round-trip adds 100-200ms of network latency. For a single request, that's barely noticeable. For an agent that makes 8-12 API calls per task (LLM calls plus tool calls plus memory lookups), it adds up to 1-2 seconds of pure network overhead.",[846,1170,1077],{"id":1171},"how-to-diagnose-it-2",[14,1173,1174,1175,1178],{},"Run ",[24,1176,1177],{},"ping"," to your LLM provider's API endpoint from your agent's server. If it's over 100ms, geography is costing you.",[14,1180,1181],{},"Compare agent response times from the same machine the agent runs on versus from your actual user location. The difference is network overhead.",[846,1183,1084],{"id":1184},"how-to-fix-it-2",[14,1186,1187,1190],{},[17,1188,1189],{},"Deploy your agent close to your LLM provider's data centers."," Most major providers (OpenAI, Anthropic, Google) have US and EU endpoints. Match your agent's region to the provider's closest endpoint.",[14,1192,1193,1196],{},[17,1194,1195],{},"Use streaming."," Instead of waiting for the full response, stream tokens to the user as they're generated. This doesn't reduce total latency, but it reduces perceived latency dramatically. The user sees the response building in real-time instead of staring at a loading spinner for 8 seconds.",[14,1198,1199,1202],{},[17,1200,1201],{},"Minimize round-trips."," Every time your agent \"thinks\" (LLM call), \"acts\" (tool call), and \"observes\" (processes result), that's at minimum three network round-trips per step. Reducing the number of steps reduces total round-trip overhead proportionally.",[14,1204,1205],{},[54,1206],{"alt":1207,"src":1208},"Every Step Multiplies Every Other Layer, a line chart of total latency against number of agent steps. An optimized agent at 1.5 seconds per step reaches 15 seconds at 10 steps; a typical agent at 3 seconds per step reaches 30 seconds; and a bloated-context agent at 5 seconds per step reaches 50 seconds, a full minute per task and unusable for users. Most tasks should end by step 5. The fastest agent solves the problem in fewer steps, not faster steps","/img/blog/ai-agent-latency-every-step-multiplies.jpg",[47,1210,1212],{"id":1211},"layer-5-multi-step-compounding-the-multiplier-nobody-talks-about","Layer 5: Multi-step compounding (the multiplier nobody talks about)",[14,1214,1215],{},"Here's where agent latency gets genuinely painful. Every additional step in your agent's workflow multiplies all the previous layers.",[14,1217,1218],{},"A single LLM call: ~800ms. Totally fine.",[14,1220,1221],{},"An orchestrator-worker flow with a reflexion loop: 10-30 seconds. Stevens Institute research puts this as the primary engineering constraint for AI agents in 2026.",[14,1223,1224],{},"A 10-step agent task means 10 LLM calls, potentially 10 tool calls, context growing with every turn, and network overhead on every round-trip. If each step takes 1.5 seconds (fast!), your total task time is 15 seconds. If each step takes 3 seconds (normal), you're at 30 seconds. At 5 seconds per step (common with context bloat), you're looking at nearly a minute.",[14,1226,1227],{},"For user-facing applications, an orchestrator-worker flow with reflection can take 10-30 seconds. For customer support, this latency is often unacceptable.",[846,1229,1231],{"id":1230},"the-honest-math","The honest math",[14,1233,1234],{},"Let's say your agent handles a support ticket. Steps: (1) read the ticket, (2) look up customer in CRM, (3) check order history, (4) check knowledge base, (5) draft response, (6) format and send.",[14,1236,1237],{},"Six steps. Each step involves at least one LLM call (800ms), one tool call (500ms average), and context processing that grows each turn. Conservative estimate: 2 seconds per step = 12 seconds total. Realistic with context bloat: 4 seconds per step = 24 seconds total.",[14,1239,1240],{},"This is why smart agent design keeps step count low. The fastest agent isn't the one with the fastest model. It's the one that solves the problem in 3 steps instead of 8.",[47,1242,1244],{"id":1243},"the-60-second-diagnostic-checklist","The 60-second diagnostic checklist",[14,1246,1247],{},"When your agent is slow, run through this in order:",[14,1249,1250],{},[54,1251],{"alt":1252,"src":1253},"The 60-Second Agent Latency Diagnostic, a five-step checklist: 1, check model TTFT by logging request-to-first-token time, and if it's under 2 seconds the model isn't the problem; 2, count input tokens, and over 30K means context bloat, so check tool defs and history; 3, time each tool call by wrapping every tool with timing logs to find the slowest; 4, check geography by pinging your LLM provider from your server, and over 100ms means move closer; 5, count your steps, and over 5 for a typical task means redesign the workflow. Most slowness is layers 2 and 5 working together, so fix those first","/img/blog/ai-agent-latency-60-second-diagnostic.jpg",[14,1255,1256,1259],{},[17,1257,1258],{},"Check model TTFT."," Log the time between request sent and first token received. If it's under 2 seconds, the model isn't your problem.",[14,1261,1262,1265],{},[17,1263,1264],{},"Count input tokens."," If your input exceeds 30,000 tokens per request, you have context bloat. Check tool definitions, conversation history, and tool results.",[14,1267,1268,1271],{},[17,1269,1270],{},"Time each tool call."," Find the slowest one. It's probably responsible for most of your tool execution latency.",[14,1273,1274,1277],{},[17,1275,1276],{},"Check geography."," Ping your LLM provider from your agent's server. If it's over 100ms, move closer.",[14,1279,1280,1283],{},[17,1281,1282],{},"Count your steps."," If your agent takes more than 5 steps for a typical task, redesign the workflow to reduce steps.",[14,1285,1286],{},"Most agent slowness is layers 2 and 5 working together. Bloated context makes each step slower. More steps means more bloated context. It's a feedback loop that gets worse with every conversation turn.",[14,1288,1289],{},"This is exactly why we built smart context management into BetterClaw from day one. Token bloat is the number one production agent killer, and most self-hosted frameworks leave you to solve it yourself. On BetterClaw, context is automatically managed per agent, tool results are filtered before entering the window, and persistent memory uses hybrid vector plus keyword retrieval so your agent doesn't drag around dead conversation weight. Free plan with every feature. $19/month per agent for Pro. BYOK with zero inference markup.",[47,1291,1293],{"id":1292},"when-switching-models-actually-helps-and-when-it-doesnt","When switching models actually helps (and when it doesn't)",[14,1295,1296],{},"After all that, there are specific cases where the model genuinely is the bottleneck:",[14,1298,1299],{},[54,1300],{"alt":1301,"src":1302},"Model Switch vs Infrastructure Fix, how to decide. Switch the model when you're using a reasoning model like o3 or GPT-5 for a simple classification task, you need faster streaming for customer-facing responses, you're running local inference where hardware is the real ceiling, or TTFT is over 2 seconds after measuring. Fix infrastructure first when context exceeds 30K tokens per request, tool calls are sequential and unparallelized, the agent takes more than 5 steps per task, or response times vary wildly between requests. The model is 800ms of a 15-second problem; fix the other 14.2 seconds first","/img/blog/ai-agent-latency-model-switch-vs-infrastructure.jpg",[14,1304,1305,1308,1309,1313],{},[17,1306,1307],{},"You're using a reasoning model for a classification task."," If your agent is classifying email urgency (simple task) using o3 or GPT-5 (reasoning model), you're paying 10-30 seconds of \"thinking\" latency for a task that Haiku or Flash can handle in 600ms. Match model size to task complexity. The framework for ",[38,1310,1312],{"href":1311},"/blog/how-to-choose-llm-for-your-task","choosing the right LLM per task"," covers this directly.",[14,1315,1316,1319],{},[17,1317,1318],{},"You need streaming for user-facing interactions."," Some providers stream faster than others. Gemini 2.5 Flash at 173 tok/s finishes a 1,100-token response in under 7 seconds. Slower models might take 20+ seconds for the same output. For customer-facing agents, streaming speed matters.",[14,1321,1322,1325,1326,1330],{},[17,1323,1324],{},"Your agent runs on local hardware."," If you're running local inference on a Mac Mini or mid-range GPU, the model is genuinely slow (3-5 seconds to first token, 30-40 tok/s). Cloud APIs are 5-10x faster for agent workloads. We break down the ",[38,1327,1329],{"href":1328},"/blog/apple-silicon-vs-nvidia-ai-agents","hardware speed gap"," in detail.",[14,1332,1333],{},"For everything else, fix layers 2-5 first. You'll get more speed improvement from trimming 50,000 tokens out of your context window than from switching to a model that's 200ms faster on TTFT.",[14,1335,1336],{},"The difference between a frustrating agent and a fast one usually isn't the model. It's whether someone bothered to measure where the latency actually lives.",[14,1338,1339,1340,1344,1345,836,1347,1350],{},"If you'd rather skip the latency debugging entirely, ",[38,1341,1343],{"href":824,"rel":1342},[826],"give BetterClaw a look",". Context management, tool optimization, caching, and infrastructure are all handled. ",[38,1346,481],{"href":480},[38,1348,1349],{"href":485},"$19/month per agent"," on Pro. Your agent deploys in 60 seconds. On infrastructure we've already optimized for speed.",[47,1352,844],{"id":843},[846,1354,1356],{"id":1355},"what-causes-ai-agent-latency","What causes AI agent latency?",[14,1358,1359],{},"AI agent latency comes from five layers: model speed (time to first token and generation rate), context window size (more tokens means more processing time per request), tool execution time (external API calls like CRM, email, or database lookups), network round-trips between your agent and API endpoints, and multi-step compounding where each workflow step multiplies all previous delays. In most cases, context bloat and step count cause more slowness than the model itself.",[846,1361,1363],{"id":1362},"how-does-llm-latency-differ-between-providers-in-2026","How does LLM latency differ between providers in 2026?",[14,1365,1366],{},"Claude Haiku 4.5 leads on time to first token at around 597ms. Gemini 2.5 Flash leads on throughput at 146-173 tokens per second. Reasoning models (o3, GPT-5, Gemini Deep Think) are intentionally slow, often 10-150 seconds to first token due to chain-of-thought processing. For agent workloads, the fastest practical choices are Gemini Flash variants for throughput and Claude Haiku for TTFT.",[846,1368,1370],{"id":1369},"how-do-i-reduce-my-ai-agents-response-time","How do I reduce my AI agent's response time?",[14,1372,1373],{},"Start by logging input token counts. If they exceed 30,000 tokens, compress conversation history into summaries, load tool definitions on demand instead of all at once, and filter tool results before they enter context. Mem0's 2026 benchmarks showed that optimized context management cut latency by 91% while improving accuracy. After fixing context, parallelize independent tool calls and reduce total workflow steps.",[846,1375,1377],{"id":1376},"does-switching-to-a-faster-llm-model-fix-agent-latency","Does switching to a faster LLM model fix agent latency?",[14,1379,1380],{},"Usually not. A single LLM call takes about 800ms. If your agent takes 15 seconds total, the model accounts for roughly 5% of the latency. The other 95% is context processing, tool execution, network overhead, and multi-step compounding. Switch models only when you're using a reasoning model for simple tasks, need faster streaming for user-facing responses, or running local inference where hardware is the genuine bottleneck.",[846,1382,1384],{"id":1383},"is-managed-hosting-faster-than-self-hosted-ai-agents","Is managed hosting faster than self-hosted AI agents?",[14,1386,1387],{},"Generally yes, for three reasons: managed platforms pre-optimize tool integrations with connection pooling and caching, they handle context management automatically to prevent token bloat, and they deploy on infrastructure close to major LLM provider data centers. BetterClaw's managed infrastructure includes smart context management, optimized integrations, and zero setup overhead. Self-hosting gives you full control but requires you to solve every latency layer yourself.",{"title":75,"searchDepth":150,"depth":150,"links":1389},[1390,1391,1392,1396,1400,1404,1407,1408,1409],{"id":1004,"depth":150,"text":1005},{"id":1020,"depth":150,"text":1021},{"id":1054,"depth":150,"text":1055,"children":1393},[1394,1395],{"id":1076,"depth":158,"text":1077},{"id":1083,"depth":158,"text":1084},{"id":1115,"depth":150,"text":1116,"children":1397},[1398,1399],{"id":1128,"depth":158,"text":1077},{"id":1134,"depth":158,"text":1084},{"id":1164,"depth":150,"text":1165,"children":1401},[1402,1403],{"id":1171,"depth":158,"text":1077},{"id":1184,"depth":158,"text":1084},{"id":1211,"depth":150,"text":1212,"children":1405},[1406],{"id":1230,"depth":158,"text":1231},{"id":1243,"depth":150,"text":1244},{"id":1292,"depth":150,"text":1293},{"id":843,"depth":150,"text":844,"children":1410},[1411,1412,1413,1414,1415],{"id":1355,"depth":158,"text":1356},{"id":1362,"depth":158,"text":1363},{"id":1369,"depth":158,"text":1370},{"id":1376,"depth":158,"text":1377},{"id":1383,"depth":158,"text":1384},"2026-06-08","AI agent taking 15+ seconds? The model isn't the bottleneck. Diagnose context bloat, tool lag, and step compounding with this 5-layer framework.","/img/blog/ai-agent-slow-latency-fix.jpg",{},"/blog/ai-agent-slow-latency-fix","11 min read",{"title":980,"description":1417},"Why Is My AI Agent So Slow? Fix Latency Fast","blog/ai-agent-slow-latency-fix",[1426,1427,1428,1429,1430,1431,1432],"ai agent slow","llm latency","reduce ai agent latency","llm inference speed","ai agent performance","context window optimization","agent response time","6-FO2dQvPYr7_yc2UaJq_cL6Lr02qBls62Y9O1dFD4I",{"id":1435,"title":1436,"author":1437,"body":1438,"category":956,"date":1912,"description":1913,"extension":959,"featured":960,"image":1914,"imageHeight":962,"imageWidth":962,"meta":1915,"navigation":161,"path":1916,"readingTime":1917,"seo":1918,"seoTitle":1919,"stem":1920,"tags":1921,"updatedDate":1928,"__hash__":1929},"blog/blog/claude-cowork-not-working-windows.md","Claude Cowork Not Working on Windows? Every Known Bug and the Best Workaround in 2026",{"name":7,"role":8,"avatar":9},{"type":11,"value":1439,"toc":1887},[1440,1445,1448,1452,1459,1462,1473,1479,1488,1495,1499,1514,1518,1521,1525,1528,1532,1535,1539,1542,1546,1549,1553,1556,1562,1566,1569,1572,1575,1578,1581,1590,1594,1597,1600,1603,1610,1617,1621,1632,1635,1643,1647,1650,1653,1656,1659,1662,1665,1671,1675,1679,1682,1707,1710,1714,1721,1744,1747,1751,1754,1758,1761,1776,1782,1786,1789,1797,1801,1804,1816,1818,1823,1826,1831,1845,1850,1860,1865,1876,1881,1884],[14,1441,1442],{},[17,1443,1444],{},"Claude Cowork fails on Windows for five reasons: (1) the CoworkVMService stops after reboot or sleep, (2) the \"yukonSilver\" platform detection bug marks capable systems as unsupported, (3) Windows Home edition lacks the full Hyper-V stack Cowork needs, (4) network conflicts with VPNs or Docker on the 172.16.0.0/24 range, and (5) corrupted installs from the old Squirrel installer. Each has a different fix.",[14,1446,1447],{},"Cowork shipped on Windows on February 10, 2026, and went GA across all paying subscribers on April 9, 2026. The Claude Code GitHub repo has been collecting Windows-specific bugs since launch: cryptic \"yukonSilver not supported\" errors, missing Cowork tabs on fully capable machines, and a VM service that resists removal. We've tracked the major failure modes and what actually fixes each one. No fluff.",[47,1449,1451],{"id":1450},"try-this-first-restart-coworkvmservice","Try this first: restart CoworkVMService",[14,1453,1454,1455,1458],{},"Before anything else, check whether Cowork's background service is actually running. CoworkVMService ships with startup type ",[17,1456,1457],{},"Manual",", which means it stops after reboots, Windows updates, and sleep/wake cycles. Once it stops, Cowork hangs or fails to connect even though everything else looks fine. This is the most common Cowork issue on Windows and the fastest one to fix.",[14,1460,1461],{},"Open PowerShell as Administrator and run:",[70,1463,1467],{"className":1464,"code":1465,"language":1466,"meta":75,"style":75},"language-powershell shiki shiki-themes github-light","sc start CoworkVMService\n","powershell",[24,1468,1469],{"__ignoreMap":75},[79,1470,1471],{"class":81,"line":82},[79,1472,1465],{},[14,1474,1475,1476,1478],{},"If that fixes Cowork until the next reboot, make it stick by switching the service to automatic startup (mind the space after ",[24,1477,605],{},"):",[70,1480,1482],{"className":1464,"code":1481,"language":1466,"meta":75,"style":75},"sc config CoworkVMService start= auto\n",[24,1483,1484],{"__ignoreMap":75},[79,1485,1486],{"class":81,"line":82},[79,1487,1481],{},[14,1489,1490,1491,1494],{},"If ",[24,1492,1493],{},"sc start"," returns \"service not found,\" skip to the install-related sections below — your Cowork installation may be broken. Otherwise, restart Claude Desktop and check the Cowork tab.",[47,1496,1498],{"id":1497},"check-your-system-before-you-debug","Check your system before you debug",[14,1500,1501,1502,1505,1506,1509,1510,1513],{},"Anthropic ships a downloadable ",[17,1503,1504],{},"Cowork readiness checker"," linked from the \"Get started with Claude Cowork\" article in Anthropic's help center (separate utility, not part of Claude Desktop). Run it first — it reports whether your machine has the Hyper-V components Cowork needs. Caveat: on Windows 11 Home it can falsely report \"ready\" because Windows 11 internally still reports as ",[24,1507,1508],{},"10.0"," and the checker misidentifies the OS (GitHub #50621). If the checker says ready but Cowork won't load, run ",[24,1511,1512],{},"Get-Service vmms"," in PowerShell — if that service doesn't exist, you're on Home and Cowork won't work.",[47,1515,1517],{"id":1516},"the-five-ways-cowork-breaks-on-windows","The Five Ways Cowork Breaks on Windows",[14,1519,1520],{},"The problems aren't random. They fall into five distinct patterns, and knowing which one you're hitting is half the battle.",[846,1522,1524],{"id":1523},"_1-the-missing-tab-yukonsilver-bug","1. The Missing Tab (yukonSilver bug)",[14,1526,1527],{},"You install Claude Desktop, open it, and the Cowork tab simply isn't there. Only \"Chat\" shows up. This is the \"yukonSilver not supported\" bug, tracked in GitHub issues #25136, #32004, and #32837. Claude's internal platform detection incorrectly marks your system as incompatible, even when all virtualization features are enabled.",[846,1529,1531],{"id":1530},"_2-the-infinite-setup-spinner","2. The Infinite Setup Spinner",[14,1533,1534],{},"The Cowork tab appears, but clicking it shows \"Setting up Claude's workspace\" with a loading bar stuck at 80 to 90%. It never completes. Users have reported leaving it running for 12+ hours with no progress. No error message. Just spinning.",[846,1536,1538],{"id":1537},"_3-the-api-connection-failure","3. The API Connection Failure",[14,1540,1541],{},"The workspace starts but can't reach Claude's API. You get \"Cannot connect to Claude API from workspace\" or its Japanese equivalent. This was a day-one launch bug on Windows 11 Home and has resurfaced multiple times since.",[846,1543,1545],{"id":1544},"_4-the-network-conflict","4. The Network Conflict",[14,1547,1548],{},"Cowork uses a hardcoded network range (172.16.0.0/24) for its internal NAT. If your home network, corporate VPN, or another VM tool uses the same range, Cowork's VM can't reach the internet. Worse, it can break your WSL2 and Docker networking in the process.",[846,1550,1552],{"id":1551},"_5-the-update-regression","5. The Update Regression",[14,1554,1555],{},"Auto-updates have introduced Cowork-breaking regressions more than once. The most-reported example was v1.1.5749 on March 9, 2026, which broke working installs and required a patch release to recover. Anthropic has since shipped multiple updates; if you're stuck on a known-bad version, updating to the current Claude Desktop release is usually the fix.",[14,1557,1558],{},[54,1559],{"alt":1560,"src":1561},"The five ways Claude Cowork breaks on Windows: missing tab, infinite spinner, API failure, network conflict, and update regression","/img/blog/claude-cowork-not-working-windows-five-bugs.jpg",[47,1563,1565],{"id":1564},"the-windows-home-problem-that-anthropic-still-hasnt-documented","The Windows Home Problem That Anthropic Still Hasn't Documented",[14,1567,1568],{},"This is where it gets messy.",[14,1570,1571],{},"Claude Cowork runs inside a lightweight Hyper-V virtual machine on your Windows machine. That's how it creates its sandboxed environment for file access and code execution. The problem? Windows 11 Home doesn't include the full Hyper-V stack.",[14,1573,1574],{},"Home edition has Virtual Machine Platform and Windows Hypervisor Platform. But it's missing the vmms (Virtual Machine Management) service that Cowork's VM requires. Without it, the VM either fails silently or throws a cryptic \"Plan9 mount failed: bad address\" error.",[14,1576,1577],{},"At least seven separate GitHub issues have been filed by Windows Home users who spent hours troubleshooting before discovering that their Windows edition simply can't run Cowork. One user explicitly noted they \"subscribed to Max specifically to use this feature\" and only discovered the incompatibility after paying.",[14,1579,1580],{},"A documentation request (GitHub issue #27906) was filed in February asking Anthropic to add this information clearly. That issue is now closed and the help center's deployment article has been updated to be more explicit about edition requirements.",[14,1582,1583,1584,1586,1587,1589],{},"The quickest check is to open PowerShell and run ",[24,1585,1512],{},". If the service isn't found, Cowork won't work without upgrading to Windows 11 Pro or Enterprise. Don't rely on Anthropic's readiness checker alone — GitHub #50621 documents that it falsely reports \"ready\" on Windows 11 Home because Windows 11 internally still reports its version as ",[24,1588,1508],{}," and the checker misclassifies the OS. A handful of community reports describe partial functionality on Home, but the official position is that Cowork requires the Pro/Enterprise Hyper-V stack.",[47,1591,1593],{"id":1592},"the-yukonsilver-bug-and-why-your-pro-machine-still-fails","The \"yukonSilver\" Bug and Why Your Pro Machine Still Fails",[14,1595,1596],{},"Stay with me here, because this one is especially frustrating.",[14,1598,1599],{},"Even if you're running Windows 11 Pro with every virtualization feature enabled (Hyper-V, VMP, WHP, WSL2), you might still see the Cowork tab missing entirely. The logs will show \"yukonSilver not supported (status=unsupported)\" followed by the VM bundle cleanup routine running instead of the actual VM boot.",[14,1601,1602],{},"\"yukonSilver\" is Claude's internal codename for its VM configuration on Windows. The bug is in the platform detection logic: it incorrectly classifies fully capable x64 Windows 11 Pro systems as unsupported.",[14,1604,1605,1606,1609],{},"But that's not even the real problem. The installer also creates a Windows service called CoworkVMService, and this service sometimes becomes impossible to remove. Running ",[24,1607,1608],{},"sc.exe delete CoworkVMService"," as Administrator returns \"Access denied.\" The service blocks clean reinstalls and creates a circular failure where you can't fix the problem and you can't start fresh.",[14,1611,1612,1613,1616],{},"The documented workaround from community debugging: manually run ",[24,1614,1615],{},"Add-AppxPackage"," as the target user to install the MSIX package correctly for your account. It's a PowerShell command that most of Cowork's target audience (non-developers) would never discover on their own.",[846,1618,1620],{"id":1619},"squirrel-vs-msix-which-installer-do-you-have","Squirrel vs. MSIX: which installer do you have?",[14,1622,1623,1624,1627,1628,1631],{},"Anthropic switched Claude Desktop on Windows from a Squirrel ",[24,1625,1626],{},".exe"," installer to an MSIX/Microsoft Store package around February 10-13, 2026. If you installed Claude Desktop before that, you have the Squirrel build, and the in-app \"Reinstall\" button can silently fail (tracked in GitHub issues #25162, #25385, #26457; error code ",[24,1629,1630],{},"0x80073CFA"," in some logs). The fix is a manual uninstall via \"Add or remove programs,\" followed by downloading the fresh MSIX from the official Claude download page. Note that MSIX installs also require Windows \"Sideload apps\" / \"Trusted App Installs\" to be enabled — without it, the MSIX install fails before it starts.",[14,1633,1634],{},"As one developer debugging the issue put it: \"Cowork is marketed at the people least equipped to debug it when it breaks.\"",[14,1636,1637,1638,1642],{},"If you've been running into similar infrastructure headaches with AI agents and want something that works out of the box, our ",[38,1639,1641],{"href":1640},"/compare/self-hosted","comparison of self-hosted vs managed OpenClaw deployments"," covers why some teams are moving away from local setups entirely.",[47,1644,1646],{"id":1645},"the-network-bug-that-breaks-docker-too","The Network Bug That Breaks Docker Too",[14,1648,1649],{},"Here's what nobody tells you about Cowork's networking on Windows.",[14,1651,1652],{},"Cowork creates its own Hyper-V virtual switch and NAT network. It's separate from WSL2's networking and separate from Docker Desktop's networking. Three different tenants sharing the same hypervisor, each with their own plumbing.",[14,1654,1655],{},"The specific failure: Cowork creates an HNS (Host Network Service) network called \"cowork-vm-nat\" but sometimes fails to create the corresponding WinNAT rule. The HNS network exists, but there's no NAT translation. The VM boots, but it has no internet access.",[14,1657,1658],{},"And in a particularly fun bug, Cowork's virtual network has been reported to permanently break WSL2's internet connectivity until you manually find and delete the offending network configuration using PowerShell HNS diagnostic tools.",[14,1660,1661],{},"The fix, discovered by community members, involves stopping all Claude processes, killing the Cowork VM via hcsdiag, removing the broken HNS network, and recreating it on a non-conflicting subnet like 172.24.0.0/24 or 10.200.0.0/24.",[14,1663,1664],{},"This is three PowerShell commands for someone who knows what they're doing. For someone who just wanted to organize their Downloads folder with AI, it's a wall.",[14,1666,1667],{},[54,1668],{"alt":1669,"src":1670},"Cowork network conflict diagram showing Hyper-V NAT, WSL2, and Docker competing on the same subnet","/img/blog/claude-cowork-not-working-windows-network-conflict.jpg",[47,1672,1674],{"id":1673},"what-actually-fixes-each-bug-quick-reference","What Actually Fixes Each Bug (Quick Reference)",[846,1676,1678],{"id":1677},"missing-cowork-tab-yukonsilver-bug","Missing Cowork Tab (yukonSilver bug)",[14,1680,1681],{},"First, confirm you're not on Windows Home. If you're on Pro or Enterprise and still don't see the tab, fully uninstall Claude Desktop, remove the leftover service, and clear residual files before reinstalling:",[70,1683,1685],{"className":1464,"code":1684,"language":1466,"meta":75,"style":75},"sc.exe stop CoworkVMService\nsc.exe delete CoworkVMService\nRemove-Item -Recurse \"$env:APPDATA\\Claude\"\nRemove-Item -Recurse \"$env:LOCALAPPDATA\\Packages\\Claude_*\"\n",[24,1686,1687,1692,1697,1702],{"__ignoreMap":75},[79,1688,1689],{"class":81,"line":82},[79,1690,1691],{},"sc.exe stop CoworkVMService\n",[79,1693,1694],{"class":81,"line":150},[79,1695,1696],{},"sc.exe delete CoworkVMService\n",[79,1698,1699],{"class":81,"line":158},[79,1700,1701],{},"Remove-Item -Recurse \"$env:APPDATA\\Claude\"\n",[79,1703,1704],{"class":81,"line":165},[79,1705,1706],{},"Remove-Item -Recurse \"$env:LOCALAPPDATA\\Packages\\Claude_*\"\n",[14,1708,1709],{},"Then reinstall fresh from the official Claude download page.",[846,1711,1713],{"id":1712},"infinite-setup-spinner","Infinite Setup Spinner",[14,1715,1716,1717,1720],{},"Two common causes here. First, the VM download itself. Look in ",[24,1718,1719],{},"%APPDATA%\\Claude\\vm_bundles\\"," — if the directory is empty or incomplete, your download was interrupted and a clean reinstall usually resolves it.",[14,1722,1723,1724,1727,1728,1731,1732,1735,1736,1739,1740,1743],{},"Second, the ",[17,1725,1726],{},"cross-drive storage path bug"," (GitHub #36642, #30584, #37754). Cowork writes ",[24,1729,1730],{},"rootfs.vhdx"," to ",[24,1733,1734],{},"C:\\Windows\\Temp"," first and then tries to rename it into its final location. If Windows \"Where new content is saved\" sends user data to a non-C: drive, that rename crosses devices and Node.js throws ",[24,1737,1738],{},"EXDEV: cross-device link not permitted",". Symptom: the spinner hangs forever with no visible error. Fix: open ",[17,1741,1742],{},"Settings → System → Storage → Advanced storage settings → Where new content is saved",", switch \"New apps\" back to the C: drive, and retry.",[14,1745,1746],{},"If the spinner persists on Windows Home, it's the Hyper-V incompatibility and there's no fix short of upgrading your edition.",[846,1748,1750],{"id":1749},"api-connection-failure","API Connection Failure",[14,1752,1753],{},"Disable your VPN temporarily (fully quit, don't just disconnect). Check whether your network uses the 172.16.0.0/24 range. If Chat works but Cowork doesn't, the problem is the VM's network stack, not your internet. Update to the latest Claude Desktop — v1.1.4328 or higher specifically addressed early API connection bugs.",[846,1755,1757],{"id":1756},"network-conflict","Network Conflict",[14,1759,1760],{},"Check whether Cowork's HNS network exists but the NAT rule doesn't:",[70,1762,1764],{"className":1464,"code":1763,"language":1466,"meta":75,"style":75},"Get-NetNat\nGet-HnsNetwork | Where-Object {$_.Name -eq \"cowork-vm-nat\"}\n",[24,1765,1766,1771],{"__ignoreMap":75},[79,1767,1768],{"class":81,"line":82},[79,1769,1770],{},"Get-NetNat\n",[79,1772,1773],{"class":81,"line":150},[79,1774,1775],{},"Get-HnsNetwork | Where-Object {$_.Name -eq \"cowork-vm-nat\"}\n",[14,1777,1490,1778,1781],{},[24,1779,1780],{},"Get-NetNat"," is empty but the HNS query returns a result, you're in the \"missing NAT rule\" state. Remove the broken network and recreate it on a non-conflicting subnet like 172.24.0.0/24 or 10.200.0.0/24.",[846,1783,1785],{"id":1784},"update-regression-v115749","Update Regression (v1.1.5749)",[14,1787,1788],{},"If Cowork broke after the March 9 update, there's no user-side fix. Update to the latest Claude Desktop release — Anthropic has shipped multiple patches since.",[14,1790,1791,1792,1796],{},"If all of this sounds like a lot of infrastructure debugging for a tool that's supposed to \"just work,\" that's because it is. This is the kind of operational friction we built ",[38,1793,1795],{"href":1794},"/","BetterClaw"," to eliminate. Your OpenClaw agent runs on managed infrastructure: no local VMs, no Hyper-V, no NAT conflicts. $19/month, BYOK, first deploy in ~60 seconds.",[47,1798,1800],{"id":1799},"cowork-vs-a-managed-agent-pick-what-matches-your-job","Cowork vs. a managed agent: pick what matches your job",[14,1802,1803],{},"Cowork is a desktop co-pilot. It runs a local Hyper-V VM, which is why every Windows edition quirk, network conflict, and update regression becomes a potential failure point. If you need a co-pilot you sit beside, that trade-off makes sense.",[14,1805,1806,1807,1811,1812,27],{},"If you need an always-on agent that handles tasks across messaging platforms while your computer is asleep, the architecture has to be different. ",[38,1808,1810],{"href":1809},"/openclaw-hosting","Managed OpenClaw hosting"," runs your agent on cloud infrastructure with Slack, Discord, WhatsApp, and 15+ channels. No local VM, no Hyper-V, no PowerShell on a Tuesday night. $19/agent/month, BYOK, first deploy in ~60 seconds. ",[38,1813,1815],{"href":824,"rel":1814},[826],"Start free",[47,1817,844],{"id":843},[14,1819,1820],{},[17,1821,1822],{},"Why is Claude Cowork not working on my Windows machine?",[14,1824,1825],{},"Top causes: CoworkVMService stopped after reboot or sleep, Windows Home edition missing the full Hyper-V stack, the \"yukonSilver\" platform detection bug, network conflicts with VPNs or Docker on 172.16.0.0/24, or a corrupted install from the old Squirrel package. Check your Windows edition, then your VM service state, then the Claude Code GitHub issues for your exact error.",[14,1827,1828],{},[17,1829,1830],{},"How do I restart CoworkVMService on Windows?",[14,1832,1833,1834,1837,1838,1841,1842,1844],{},"Open PowerShell as Administrator and run ",[24,1835,1836],{},"sc start CoworkVMService"," to start it for the current session. To make it survive reboots, run ",[24,1839,1840],{},"sc config CoworkVMService start= auto"," (mind the space after ",[24,1843,605],{},"). The service ships with startup type Manual, so it stops after reboots, Windows updates, and sleep/wake cycles. This is the single most common Cowork fix on Windows.",[14,1846,1847],{},[17,1848,1849],{},"Does Claude Cowork work on Windows 11 Home?",[14,1851,1852,1853,1856,1857,1859],{},"No, officially. Cowork requires the Hyper-V ",[24,1854,1855],{},"vmms"," service, which Home editions lack. Anthropic's readiness checker can falsely report Home as \"ready\" (it misidentifies the OS), so don't trust it alone — run ",[24,1858,1512],{}," in PowerShell. If it's missing, upgrade to Windows 11 Pro or Enterprise.",[14,1861,1862],{},[17,1863,1864],{},"How do I fix the \"yukonSilver not supported\" error in Claude Cowork?",[14,1866,1867,1868,1871,1872,1875],{},"This is a platform detection bug on Claude's side, still open as of May 2026. The workaround: fully uninstall Claude Desktop, stop and delete CoworkVMService via elevated PowerShell, clear ",[24,1869,1870],{},"%APPDATA%\\Claude"," and the ",[24,1873,1874],{},"%LOCALAPPDATA%\\Packages\\Claude_*"," folder, then reinstall fresh from the official download.",[14,1877,1878],{},[17,1879,1880],{},"Is Claude Cowork on Windows stable enough for daily use in 2026?",[14,1882,1883],{},"Cowork went GA in April 2026, but Windows is still the rougher platform. The yukonSilver bug remains open, the CoworkVMService Manual-startup behavior catches users after every reboot, and update regressions appear periodically. Fine for desktop tasks if your system is compatible. For workloads where downtime means lost work, a managed agent is more reliable.",[935,1885,1886],{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":75,"searchDepth":150,"depth":150,"links":1888},[1889,1890,1891,1898,1899,1902,1903,1910,1911],{"id":1450,"depth":150,"text":1451},{"id":1497,"depth":150,"text":1498},{"id":1516,"depth":150,"text":1517,"children":1892},[1893,1894,1895,1896,1897],{"id":1523,"depth":158,"text":1524},{"id":1530,"depth":158,"text":1531},{"id":1537,"depth":158,"text":1538},{"id":1544,"depth":158,"text":1545},{"id":1551,"depth":158,"text":1552},{"id":1564,"depth":150,"text":1565},{"id":1592,"depth":150,"text":1593,"children":1900},[1901],{"id":1619,"depth":158,"text":1620},{"id":1645,"depth":150,"text":1646},{"id":1673,"depth":150,"text":1674,"children":1904},[1905,1906,1907,1908,1909],{"id":1677,"depth":158,"text":1678},{"id":1712,"depth":158,"text":1713},{"id":1749,"depth":158,"text":1750},{"id":1756,"depth":158,"text":1757},{"id":1784,"depth":158,"text":1785},{"id":1799,"depth":150,"text":1800},{"id":843,"depth":150,"text":844},"2026-03-27","Claude Cowork broken on Windows? Covers 5 failure modes: yukonSilver bug, Windows Home limits, VM service stops, network conflicts, and update regressions. Step-by-step fixes.","/img/blog/claude-cowork-not-working-windows.jpg",{},"/blog/claude-cowork-not-working-windows","14 min read",{"title":1436,"description":1913},"Claude Cowork Not Working on Windows? 5 Fixes (2026)","blog/claude-cowork-not-working-windows",[1922,1923,1924,1925,1926,1927],"Claude Cowork not working Windows","Cowork Windows bugs","yukonSilver error","Claude Cowork Windows fix","Cowork Hyper-V","Cowork Windows Home","2026-05-19","Sq06kygerdAX6Y2Mxv3OPy2yjFOapLcXpUWGeKLwStI",{"id":1931,"title":1932,"author":1933,"body":1934,"category":956,"date":2497,"description":2498,"extension":959,"featured":960,"image":2499,"imageHeight":962,"imageWidth":962,"meta":2500,"navigation":161,"path":2501,"readingTime":1421,"seo":2502,"seoTitle":2503,"stem":2504,"tags":2505,"updatedDate":2497,"__hash__":2512},"blog/blog/debug-mcp-tool-calls.md","How to Debug MCP Tool Calls: The Troubleshooting Workflow That Finds the Problem in 5 Minutes",{"name":7,"role":8,"avatar":9},{"type":11,"value":1935,"toc":2482},[1936,1982,1985,1988,1991,1998,2001,2009,2012,2016,2023,2029,2035,2045,2050,2087,2090,2094,2097,2102,2107,2142,2153,2157,2160,2165,2171,2176,2225,2229,2232,2241,2246,2266,2272,2275,2279,2282,2287,2319,2323,2326,2332,2403,2406,2421,2424,2435,2437,2441,2444,2448,2455,2459,2465,2469,2475,2479],[1937,1938,1940],"callout",{"type":1939},"quick-fix",[14,1941,1942,1945,1946,1949,1950,1953,1954,1957,1958,1961,1962,1965,1966,1969,1970,1973,1974,1977,1978,1981],{},[17,1943,1944],{},"Quick fix:"," MCP tool failures are silent by default — the agent just proceeds without the tool, often hallucinating an answer. Work this five-stage decision tree in order and stop when you find the break: ",[17,1947,1948],{},"(1) Handshake"," — is the server connected? (the #1 culprit is stdout corruption: a ",[24,1951,1952],{},"console.log"," before the JSON-RPC stream — make every log ",[24,1955,1956],{},"console.error","). ",[17,1959,1960],{},"(2) Discovery"," — does the client see the tool? (restart the client; it caches the list). ",[17,1963,1964],{},"(3) Schema"," — do parameter types and enum values match exactly? ",[17,1967,1968],{},"(4) Invocation"," — does the handler fire? (add stderr logging, check timeouts). ",[17,1971,1972],{},"(5) Parsing"," — did the response reach the model? (truncate large responses, use the ",[24,1975,1976],{},"content"," array). Add a ",[24,1979,1980],{},"health_check"," tool to every server to triage in under 60 seconds.",[14,1983,1984],{},"Your agent silently skips a tool call. No error. No log. No clue what happened. Here's the five-stage diagnostic decision tree that catches every MCP failure mode.",[14,1986,1987],{},"The agent was supposed to query our database. It didn't. No error message. No timeout. No indication anything went wrong. The agent just... continued without the data. Answered the user's question with a confident hallucination instead of actual numbers.",[14,1989,1990],{},"I checked the logs. Nothing. The MCP server was running. The tool was registered. The schema looked correct. Everything appeared fine.",[14,1992,1993,1994,1997],{},"Forty-five minutes of staring at config files later, I found it. The server was printing a debug log line to stdout before the JSON-RPC handshake completed. One ",[24,1995,1996],{},"console.log(\"server starting...\")"," was corrupting the entire protocol stream. The client couldn't parse the initialization response, silently gave up on that server, and the agent proceeded without tools.",[14,1999,2000],{},"One print statement. Forty-five minutes of debugging. Zero error messages.",[14,2002,2003,2004,2008],{},"If you need to debug MCP tool calls, the problem is almost never where you think it is. (New to the protocol itself? Start with ",[38,2005,2007],{"href":2006},"/blog/what-is-mcp-model-context-protocol","what MCP is and how it works",", then come back here.) MCP failures are silent by default. The protocol doesn't throw visible errors when things go wrong. It just... stops working. Your agent doesn't know it lost a tool. It carries on without it.",[14,2010,2011],{},"Here's the five-stage diagnostic workflow that catches every failure mode. Work through it in order. Stop when you find the break.",[47,2013,2015],{"id":2014},"stage-1-handshake-can-the-client-talk-to-the-server-at-all","Stage 1: Handshake (can the client talk to the server at all?)",[14,2017,2018,2019,2022],{},"Before debugging tools, verify the connection exists. The MCP handshake is the ",[24,2020,2021],{},"initialize"," exchange between client and server. If it fails, nothing else matters.",[14,2024,2025],{},[54,2026],{"alt":2027,"src":2028},"Stage 1 handshake debug flow: if the initialize exchange fails, check the server path, stdout corruption, port conflicts, and transport type before moving on","/img/blog/debug-mcp-tool-calls-handshake.jpg",[14,2030,2031,2034],{},[17,2032,2033],{},"Test it:"," Open the MCP Inspector (the official debugging tool from the MCP team). Copy your server's command, args, and env from your MCP client config. Paste them into Inspector's connection dialog. Hit connect.",[14,2036,2037,2038,2041,2042,2044],{},"Inspector opens at ",[24,2039,2040],{},"http://localhost:6274",". It shows the raw JSON-RPC messages. If the handshake succeeds, you'll see an ",[24,2043,2021],{}," request and a capabilities response.",[14,2046,2047],{},[17,2048,2049],{},"Common handshake failures:",[2051,2052,2053,2060,2072,2081],"ul",{},[2054,2055,2056,2059],"li",{},[17,2057,2058],{},"Wrong path to the server binary."," The most common failure. Use absolute paths. Run the command manually in your terminal first. If it doesn't work in your terminal, it won't work in MCP.",[2054,2061,2062,2065,2066,2068,2069,2071],{},[17,2063,2064],{},"stdout corruption."," This is the silent killer. Your server prints something to stdout (a debug log, a startup message, a warning) before the JSON-RPC stream begins. The client tries to parse \"Server starting...\" as JSON. Fails silently. Redirect all non-protocol output to stderr. Every ",[24,2067,1952],{}," in your MCP server should be ",[24,2070,1956],{}," (which goes to stderr) unless it's an actual JSON-RPC response.",[2054,2073,2074,2077,2078,27],{},[17,2075,2076],{},"Port conflicts."," Inspector uses ports 6274 and 6277. If another service occupies them, Inspector can't start. Check with ",[24,2079,2080],{},"lsof -i :6274",[2054,2082,2083,2086],{},[17,2084,2085],{},"Wrong transport type."," STDIO for local servers (you provide a command). Streamable HTTP for remote servers (you provide a URL). Selecting the wrong one in Inspector produces a connection error that doesn't explain itself.",[14,2088,2089],{},"Stdout corruption is the #1 silent MCP failure. One print statement before the handshake corrupts the entire protocol stream. The fix takes 10 seconds. Finding it without knowing to look takes 45 minutes.",[47,2091,2093],{"id":2092},"stage-2-discovery-can-the-client-see-the-tools","Stage 2: Discovery (can the client see the tools?)",[14,2095,2096],{},"The handshake worked. The server is connected. But does the client see your tools?",[14,2098,2099,2101],{},[17,2100,2033],{}," In MCP Inspector, click \"List Tools.\" You should see every tool your server exposes, with names and schemas.",[14,2103,2104],{},[17,2105,2106],{},"If tools are missing:",[2051,2108,2109,2119,2129],{},[2054,2110,2111,2114,2115,2118],{},[17,2112,2113],{},"The tool handler isn't registered."," Your server code defines the tool but doesn't register it in the MCP handler. Different SDKs have different registration patterns. In the Python SDK, you use ",[24,2116,2117],{},"@server.tool()"," decorators. In TypeScript, you add tools to the server's tool list. A tool that exists in your code but isn't registered in the MCP handler simply doesn't appear.",[2054,2120,2121,2124,2125,2128],{},[17,2122,2123],{},"The server started before the tool was registered."," Race condition. If your server answers ",[24,2126,2127],{},"tools/list"," before all tool handlers are loaded (common in async setups), the client gets an incomplete list. The client caches this list and doesn't re-request it.",[2054,2130,2131,2134,2135,2137,2138,2141],{},[17,2132,2133],{},"The MCP client is caching a stale tool list."," Claude Desktop, Cursor, and Codex CLI all cache the tool list after the first ",[24,2136,2127],{}," response. If you add a new tool and restart the server but not the client, the client still sees the old list. Restart both. Or in Codex CLI v0.123+, run ",[24,2139,2140],{},"/mcp verbose"," to force a fresh discovery.",[14,2143,2144,2147,2148,2152],{},[17,2145,2146],{},"If the tool appears but the agent doesn't use it:"," This isn't a discovery problem. It's a model behavior problem. (If your model can't call tools at all, that's a different issue — see ",[38,2149,2151],{"href":2150},"/blog/openclaw-model-does-not-support-tools","when your model doesn't support tools",".) The model sees the tool but decides not to call it. Check: is the tool name clear? Is the description informative? Does the schema accurately describe what the tool does? Models pick tools based on name and description, not your intent.",[47,2154,2156],{"id":2155},"stage-3-schema-validation-does-the-tool-definition-match-what-the-model-expects","Stage 3: Schema validation (does the tool definition match what the model expects?)",[14,2158,2159],{},"The tool is visible. The model should be calling it. But the call either fails or produces garbage.",[14,2161,2162,2164],{},[17,2163,2033],{}," In Inspector, click the tool and examine its JSON schema. Then manually call it with test parameters. Does it return what you expect?",[14,2166,2167],{},[54,2168],{"alt":2169,"src":2170},"Stage 3 schema validation checklist: required fields marked correctly, parameter types match the handler, enum values match exactly, description tells the model when and how to use the tool, and Inspector returns expected data","/img/blog/debug-mcp-tool-calls-schema-checklist.jpg",[14,2172,2173],{},[17,2174,2175],{},"Common schema failures:",[2051,2177,2178,2184,2201,2219],{},[2054,2179,2180,2183],{},[17,2181,2182],{},"Required parameters marked as optional (or vice versa)."," The model provides what the schema says. If a required parameter is marked optional, the model might skip it. The tool receives null and crashes or returns an empty result.",[2054,2185,2186,2189,2190,2193,2194,2196,2197,2200],{},[17,2187,2188],{},"Type mismatches."," Your tool expects an integer but the schema says string. The model sends ",[24,2191,2192],{},"\"42\""," (string). Your handler receives ",[24,2195,2192],{}," (string) instead of ",[24,2198,2199],{},"42"," (integer) and the comparison or calculation fails silently.",[2054,2202,2203,2206,2207,2210,2211,2214,2215,2218],{},[17,2204,2205],{},"Enum values that don't match."," Your schema says the ",[24,2208,2209],{},"status"," parameter accepts ",[24,2212,2213],{},"[\"active\", \"inactive\"]",". Your backend code checks for ",[24,2216,2217],{},"[\"Active\", \"Inactive\"]"," (capitalized). The model sends the schema's values. Your code doesn't match. No error, just no results.",[2054,2220,2221,2224],{},[17,2222,2223],{},"Description too vague."," The model uses the tool description to decide WHEN to call the tool and WHAT to pass. A description like \"Queries the database\" doesn't tell the model what kind of queries, what parameters to construct, or what results to expect. Be specific: \"Queries the customer database by email address and returns account status, plan type, and last login date.\"",[47,2226,2228],{"id":2227},"stage-4-invocation-did-the-tool-actually-run","Stage 4: Invocation (did the tool actually run?)",[14,2230,2231],{},"Schema looks good. The model calls the tool. But did the server actually execute the handler?",[14,2233,2234,2236,2237,2240],{},[17,2235,2033],{}," Add a log line to the very first line of your tool handler: ",[24,2238,2239],{},"console.error(\"TOOL CALLED: toolName\", params)",". (Remember: stderr, not stdout.) Then trigger the agent and check your server's error output.",[14,2242,2243],{},[17,2244,2245],{},"If the handler never fires:",[2051,2247,2248,2254,2260],{},[2054,2249,2250,2253],{},[17,2251,2252],{},"The client sent the request but the server didn't receive it."," Transport issue. If you're using STDIO, the message might be stuck in a buffer. If you're using Streamable HTTP, the request might have timed out before reaching the server. Check your server's network logs.",[2054,2255,2256,2259],{},[17,2257,2258],{},"The server received the request but crashed before reaching your handler."," A middleware or authentication check failed silently. Add try-catch at the server level (not just the handler level) to log any errors during request routing.",[2054,2261,2262,2265],{},[17,2263,2264],{},"Timeout."," The client has a timeout for tool calls (varies by client: Claude Desktop is generous, Codex CLI's default is shorter). If your tool takes longer than the timeout, the client cancels the call. The server may still be processing. The agent gets nothing. Check your client-specific timeout settings and increase if your tools are legitimately slow.",[14,2267,2268,2271],{},[17,2269,2270],{},"If the handler fires but returns an error:"," The tool ran but threw an exception. Without proper error handling, the exception propagates as a JSON-RPC error that the model may not understand. Always return a clear error message from your handler rather than letting exceptions bubble up raw.",[14,2273,2274],{},"This is exactly the kind of debugging that makes self-hosted agent frameworks time-consuming. On BetterClaw, tool integrations are pre-built, tested, and monitored. 200+ verified skills with built-in error handling, retry logic, and health monitoring. No MCP server to configure. No JSON-RPC to debug. No stdout corruption to hunt for. Free plan with every feature. $19/month per agent on Pro. BYOK with zero markup.",[47,2276,2278],{"id":2277},"stage-5-parsing-did-the-response-make-it-back-to-the-model-correctly","Stage 5: Parsing (did the response make it back to the model correctly?)",[14,2280,2281],{},"The tool ran. It returned data. But the model's response doesn't reflect the tool results.",[14,2283,2284],{},[17,2285,2286],{},"Common parsing failures:",[2051,2288,2289,2295,2301,2313],{},[2054,2290,2291,2294],{},[17,2292,2293],{},"Response too large."," Your tool returned 50,000 tokens of data. The model's context window filled up. Critical information got pushed out. Truncate tool responses to what the model actually needs. Return summaries, not raw dumps.",[2054,2296,2297,2300],{},[17,2298,2299],{},"Response format the model can't use."," You returned raw HTML, a binary blob, or deeply nested JSON that the model can't parse meaningfully. Return clean, flat JSON with descriptive field names.",[2054,2302,2303,2306,2307,2309,2310,2312],{},[17,2304,2305],{},"Content field missing."," The MCP response must include a ",[24,2308,1976],{}," array with at least one text or image block. If your server returns data outside the ",[24,2311,1976],{}," field, the client may ignore it.",[2054,2314,2315,2318],{},[17,2316,2317],{},"The model ignores the tool result."," This happens when the tool result contradicts the model's prior reasoning. The model decides its initial answer was \"probably right\" and doesn't update. This isn't an MCP bug. It's a model behavior issue. Improve your system prompt to instruct the model to always prioritize tool results over its own knowledge.",[47,2320,2322],{"id":2321},"the-quick-reference-fix-table","The quick-reference fix table",[14,2324,2325],{},"Here's the full diagnostic table. Start at the top. Stop when you find your issue.",[14,2327,2328],{},[54,2329],{"alt":2330,"src":2331},"MCP debug quick reference: each symptom mapped to its stage and the first thing to check, from \"no tools used\" (Stage 1, handshake) to \"broke overnight\" (restart both client and server)","/img/blog/debug-mcp-tool-calls-quick-reference.jpg",[2333,2334,2335,2348],"table",{},[2336,2337,2338],"thead",{},[2339,2340,2341,2345],"tr",{},[2342,2343,2344],"th",{},"Symptom",[2342,2346,2347],{},"Check",[2349,2350,2351,2360,2368,2376,2384,2395],"tbody",{},[2339,2352,2353,2357],{},[2354,2355,2356],"td",{},"Agent doesn't use any tools",[2354,2358,2359],{},"Stage 1 (handshake). Is the MCP server connected? Run Inspector.",[2339,2361,2362,2365],{},[2354,2363,2364],{},"Agent uses some tools but not the new one",[2354,2366,2367],{},"Stage 2 (discovery). Is the tool registered? Did you restart the client after adding it?",[2339,2369,2370,2373],{},[2354,2371,2372],{},"Agent calls the tool but gets wrong results",[2354,2374,2375],{},"Stage 3 (schema). Do parameter types and enum values match exactly?",[2339,2377,2378,2381],{},[2354,2379,2380],{},"Agent calls the tool but nothing happens",[2354,2382,2383],{},"Stage 4 (invocation). Does the handler fire? Add stderr logging. Check timeouts.",[2339,2385,2386,2389],{},[2354,2387,2388],{},"Tool returns correct data but agent ignores it",[2354,2390,2391,2392,2394],{},"Stage 5 (parsing). Is the response too large? Is it in the ",[24,2393,1976],{}," field? Does the system prompt prioritize tool results?",[2339,2396,2397,2400],{},[2354,2398,2399],{},"Everything worked yesterday, broken today",[2354,2401,2402],{},"Server update changed the tool list or schema. Client cached the old list. Restart both.",[14,2404,2405],{},"MCP has 97 million downloads as of 2026. It's the standard for connecting agents to tools. But the debugging experience is still rough. Gartner projects 40% of enterprise applications will embed AI agents by end of 2026. Every one of those agents will use tools. Every one of those tool integrations will break at some point. The teams that can diagnose MCP failures in 5 minutes instead of 45 will ship faster and sleep better.",[14,2407,2408,2409,2413,2414,2416,2417,2420],{},"If you're still wiring up your first server, our ",[38,2410,2412],{"href":2411},"/blog/openclaw-mcp-setup-guide","MCP setup guide"," walks through the connection step by step. The single best debugging habit you can build: add a health check tool to every MCP server. A tool called ",[24,2415,1980],{}," that takes no parameters and returns ",[24,2418,2419],{},"{\"status\": \"ok\", \"tools_count\": N}",". If this tool works, your handshake, discovery, and basic invocation are fine. If it doesn't, start at Stage 1.",[14,2422,2423],{},"MCP debugging will get better. Inspector will evolve. Proxy-based logging will mature. Client error reporting will improve. But right now, in mid-2026, silent failures are the norm, and the five-stage workflow above is the fastest path from \"something's broken\" to \"found it, fixed it.\"",[14,2425,2426,2429,2430,836,2432,2434],{},[38,2427,827],{"href":824,"rel":2428},[826]," if you'd rather skip MCP debugging entirely. Pre-built integrations with 25+ OAuth services. Managed tool connections. Built-in error handling and health monitoring. ",[38,2431,481],{"href":480},[38,2433,486],{"href":485},". We handle the protocol plumbing. You handle what the agent actually does.",[47,2436,844],{"id":843},[846,2438,2440],{"id":2439},"what-does-it-mean-to-debug-mcp-tool-calls","What does it mean to debug MCP tool calls?",[14,2442,2443],{},"Debugging MCP tool calls means diagnosing why an AI agent fails to invoke, execute, or process the results of a tool connected via the Model Context Protocol. MCP failures are typically silent: the agent doesn't throw an error, it simply proceeds without the tool data, often hallucinating an answer instead. The debugging process follows a five-stage decision tree: handshake (is the server connected?), discovery (can the client see the tools?), schema validation (do the definitions match?), invocation (did the tool actually run?), and parsing (did the response reach the model correctly?).",[846,2445,2447],{"id":2446},"how-does-the-mcp-inspector-help-with-debugging","How does the MCP Inspector help with debugging?",[14,2449,2450,2451,2454],{},"MCP Inspector is the official debugging tool from the MCP team. It provides a browser-based UI (at ",[24,2452,2453],{},"localhost:6274",") where you can see the raw JSON-RPC messages between client and server, list all registered tools, call individual tools with test parameters, and inspect responses. The key limitation: Inspector acts as its own client, not a proxy. It shows Inspector-to-server traffic, not your actual agent-to-server traffic. If a tool works in Inspector but fails in your agent client (Claude, Cursor, Codex), the problem is client-specific.",[846,2456,2458],{"id":2457},"how-do-i-fix-an-mcp-tool-that-silently-fails-to-fire","How do I fix an MCP tool that silently fails to fire?",[14,2460,2461,2462,2464],{},"Start with the most common cause: stdout corruption. Check if your MCP server prints anything to stdout before the JSON-RPC stream (startup messages, debug logs, warnings). Redirect all non-protocol output to stderr. Then verify in MCP Inspector that the tool appears in the ",[24,2463,2127],{}," response and that calling it with test parameters returns expected data. If it works in Inspector but not in your client, restart the client (it caches the tool list) and check client-specific timeout settings.",[846,2466,2468],{"id":2467},"how-much-time-does-mcp-debugging-typically-take","How much time does MCP debugging typically take?",[14,2470,2471,2472,2474],{},"With the five-stage diagnostic workflow, most MCP tool call failures can be identified in 5-15 minutes. Without a structured approach, developers commonly report spending 30-60 minutes on what turns out to be a simple configuration issue (wrong path, stdout corruption, stale cache). The most time-consuming failures are Stage 4 (invocation) issues where the handler fires but returns unexpected data, which requires testing with real inputs. Adding a ",[24,2473,1980],{}," tool to every MCP server reduces initial triage to under 60 seconds.",[846,2476,2478],{"id":2477},"is-mcp-reliable-enough-for-production-agent-deployments","Is MCP reliable enough for production agent deployments?",[14,2480,2481],{},"MCP is the dominant agent-to-tool protocol with 97 million downloads and adoption by Anthropic, OpenAI, Google, and Microsoft. It's production-ready. The debugging challenges are real but solvable with proper monitoring: add health check tools, log to stderr, use gateway proxies for production observability, and restart both client and server after any tool changes. For teams that want to skip MCP configuration entirely, managed platforms like BetterClaw provide pre-built integrations with built-in error handling, retries, and health monitoring across 200+ verified skills.",{"title":75,"searchDepth":150,"depth":150,"links":2483},[2484,2485,2486,2487,2488,2489,2490],{"id":2014,"depth":150,"text":2015},{"id":2092,"depth":150,"text":2093},{"id":2155,"depth":150,"text":2156},{"id":2227,"depth":150,"text":2228},{"id":2277,"depth":150,"text":2278},{"id":2321,"depth":150,"text":2322},{"id":843,"depth":150,"text":844,"children":2491},[2492,2493,2494,2495,2496],{"id":2439,"depth":158,"text":2440},{"id":2446,"depth":158,"text":2447},{"id":2457,"depth":158,"text":2458},{"id":2467,"depth":158,"text":2468},{"id":2477,"depth":158,"text":2478},"2026-06-15","MCP tool not firing? No error, no log? Walk through this 5-stage decision tree to find the break in under 5 minutes. Fix table included.","/img/blog/debug-mcp-tool-calls.jpg",{},"/blog/debug-mcp-tool-calls",{"title":1932,"description":2498},"Debug MCP Tool Calls: 5-Stage Troubleshooting Guide","blog/debug-mcp-tool-calls",[2506,2507,2508,2509,2510,2511],"debug mcp tool calls","mcp tool not firing","mcp inspector","mcp tool call logging","mcp debugging","mcp troubleshooting","eBK7mSPN4PIpcI4_eIbSPRppyL68XIdR-rAufEGCD10",1782132001199]