[{"data":1,"prerenderedAt":1500},["ShallowReactive",2],{"docs:\u002Ftroubleshooting":3},{"id":4,"title":5,"accent":6,"body":7,"description":1463,"estReadTime":1464,"extension":1465,"eyebrow":1466,"icon":1467,"intro":1468,"lastUpdated":1468,"meta":1469,"navigation":647,"next":1470,"path":1473,"prev":1474,"review":1468,"seo":1477,"stem":6,"tocItems":1491,"__hash__":1499},"docs\u002Ftroubleshooting.md","Troubleshooting","troubleshooting",{"type":8,"value":9,"toc":1438},"minimark",[10,14,142,244,543,837,1019,1167,1434],[11,12,13],"p",{},"This chapter is organized by symptom, not by cause. You landed here because something is broken — find the heading that matches what you're seeing, read the \"likely cause\" list in order (most common first), and apply the fix. Most of these take under two minutes once you know where to look.",[15,16,19,26,31,92,96,107,123,127],"docs-section",{"id":17,"title":18},"missing-file","Claude Can't See My File",[11,20,21,25],{},[22,23,24],"strong",{},"Symptom"," — Claude says a file doesn't exist, or reads an old version, or claims a folder is empty when you can see files in your editor.",[27,28,30],"h3",{"id":29},"likely-causes-check-in-this-order","Likely causes (check in this order)",[32,33,34,41,58,72,86],"ol",{},[35,36,37,40],"li",{},[22,38,39],{},"Claude's cwd isn't where you think it is."," Subagents especially start with their own cwd. This is the #1 cause.",[35,42,43,54,55,57],{},[22,44,45,49,50,53],{},[46,47,48],"code",{},".gitignore"," or ",[46,51,52],{},"permissions.deny"," is hiding the file."," Claude respects gitignore for searches; ",[46,56,52],{}," blocks reads explicitly.",[35,59,60,63,64,67,68,71],{},[22,61,62],{},"Wrong path or case mismatch."," ",[46,65,66],{},"components\u002FButton.tsx"," vs ",[46,69,70],{},"components\u002Fbutton.tsx"," — macOS forgives, Linux doesn't.",[35,73,74,77,78,81,82,85],{},[22,75,76],{},"Git worktree confusion."," You opened Claude from ",[46,79,80],{},"..\u002Frepo-feat"," but keep giving it paths from ",[46,83,84],{},"..\u002Frepo",".",[35,87,88,91],{},[22,89,90],{},"File type excluded."," Very large files, binaries, and some lock files are skipped silently.",[27,93,95],{"id":94},"fix","Fix",[97,98,105],"pre",{"className":99,"code":101,"filename":102,"language":103,"meta":104},[100],"language-text","Before you look for the file, run:\n  1. pwd\n  2. ls -la\n  3. git check-ignore -v \u003Cthe-path-you-expect>\n  4. cat .claude\u002Fsettings.json | jq '.permissions.deny \u002F\u002F []'\n  5. git worktree list\n\nThen tell me where you think the file is and where you actually are.\n","diagnostic prompt","text","",[46,106,101],{"__ignoreMap":104},[11,108,109,110,112,113,116,117,119,120,85],{},"If ",[46,111,48],{}," is filtering it out of search results, point Claude at the explicit path with ",[46,114,115],{},"Read"," — gitignore affects listing and searching, not explicit reads. If ",[46,118,52],{}," is blocking it, remove or narrow the rule in ",[46,121,122],{},".claude\u002Fsettings.json",[27,124,126],{"id":125},"prevention","Prevention",[11,128,129,130,132,133,135,136,141],{},"Get ",[46,131,48],{}," right before anything else, and use ",[46,134,52],{}," surgically — see ",[137,138,140],"a",{"href":139},"\u002Ffoundations#hiding-files","Foundations → Hiding Files from Claude",". The 30-second setup prevents a full category of \"it's missing\" confusion.",[15,143,146,155,159,189,193,200,207,219,226],{"id":144,"title":145},"out-of-context","Out of Context Errors",[11,147,148,150,151,154],{},[22,149,24],{}," — \"conversation too long\" error, sudden refusals that feel off, Claude forgets instructions from earlier, or ",[46,152,153],{},"\u002Fcontext"," shows 80%+.",[27,156,158],{"id":157},"likely-causes","Likely causes",[32,160,161,167,173,183],{},[35,162,163,166],{},[22,164,165],{},"You've crossed the 200K ceiling."," Hard limit. The request can't be sent.",[35,168,169,172],{},[22,170,171],{},"You're above 80% and performance is degrading."," Not yet an error — but the next prompt might be.",[35,174,175,178,179,182],{},[22,176,177],{},"A tool dumped a huge blob into context."," A file read, a ",[46,180,181],{},"curl"," output, a log that streamed thousands of lines.",[35,184,185,188],{},[22,186,187],{},"A subagent returned a massive summary."," Subagents should summarize to ~2K. Sometimes they don't.",[27,190,192],{"id":191},"fix-in-order-of-escalation","Fix (in order of escalation)",[97,194,198],{"className":195,"code":196,"filename":197,"language":103,"meta":104},[100],"\u002Fcontext       # see the breakdown\n\u002Fcompact       # compresses conversation history (see the warning below)\n","fix 1 — free up headroom immediately",[46,199,196],{"__ignoreMap":104},[97,201,205],{"className":202,"code":203,"filename":204,"language":103,"meta":104},[100],"Before I \u002Fclear, write .claude\u002Fhandoff.md with:\n  - Current status (done \u002F not done)\n  - The next concrete step\n  - Open questions\n  - Exact commands to resume\nKeep it under 40 lines.\n","fix 2 — hand off to a fresh session",[46,206,203],{"__ignoreMap":104},[11,208,209,210,213,214,218],{},"Then ",[46,211,212],{},"\u002Fclear",", start a new session, and open the handoff. See ",[137,215,217],{"href":216},"\u002Fworkflows#handoff","Workflows → Context Handoff"," for the full pattern.",[97,220,224],{"className":221,"code":222,"filename":223,"language":103,"meta":104},[100],"# Set the StatusLine to show your context percentage\n# See Foundations → The Context Window for the settings.json snippet.\n","fix 3 — prevent the next one",[46,225,222],{"__ignoreMap":104},[227,228,231],"docs-callout",{"title":229,"variant":230},"\u002Fcompact is not a free lunch","warning",[11,232,233,236,237,239,240,85],{},[46,234,235],{},"\u002Fcompact"," rewrites your history into a summary. Useful, but Claude loses the literal turns — the exact prompt wording, the exact tool outputs. For anything where detail matters (bugfix traces, mid-review conversations), a handoff doc beats ",[46,238,235],{},". See ",[137,241,243],{"href":242},"\u002Fworkflows#sessions","Workflows → Session Management",[15,245,248,256,259,312,316,322,488,491,510,529,532],{"id":246,"title":247},"hook","Hook Didn't Fire",[11,249,250,252,253,255],{},[22,251,24],{}," — You wrote a hook in ",[46,254,122],{},". Claude does the trigger action. Nothing happens. No error, no log, nothing.",[27,257,158],{"id":258},"likely-causes-1",[32,260,261,274,287,300,306],{},[35,262,263,266,267,67,270,273],{},[22,264,265],{},"Settings file isn't loaded."," Wrong path (",[46,268,269],{},".claude\u002Fsettings.local.json",[46,271,272],{},"settings.json","), or JSON syntax error that silently invalidates the file.",[35,275,276,63,279,282,283,286],{},[22,277,278],{},"Matcher doesn't match.",[46,280,281],{},"\"Edit|Write\""," matches literally — if you meant to catch ",[46,284,285],{},"MultiEdit",", add it explicitly.",[35,288,289,63,292,295,296,299],{},[22,290,291],{},"Wrong event name.",[46,293,294],{},"PostToolUse"," ≠ ",[46,297,298],{},"postToolUse",". Case-sensitive.",[35,301,302,305],{},[22,303,304],{},"Command fails silently."," Hook command exits non-zero before doing anything visible.",[35,307,308,311],{},[22,309,310],{},"Timeout too short."," Hook takes 15 seconds, default timeout kills it at 10.",[27,313,315],{"id":314},"fix-the-two-line-diagnostic-hook","Fix — the two-line diagnostic hook",[11,317,318,319,321],{},"Add this to ",[46,320,122],{}," first. It proves the hook plumbing works, separate from whatever your real hook is trying to do.",[97,323,327],{"className":324,"code":325,"filename":122,"language":326,"meta":104,"style":104},"language-json shiki shiki-themes github-light","{\n  \"hooks\": {\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Edit|Write|MultiEdit\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"echo \\\"[hook] $(date) fired on $(echo \\\\\\\"$CLAUDE_TOOL_NAME\\\\\\\")\\\" >> \u002Ftmp\u002Fclaude-hook.log\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ]\n  }\n}\n","json",[46,328,329,338,348,357,363,379,387,393,406,441,452,458,464,470,476,482],{"__ignoreMap":104},[330,331,334],"span",{"class":332,"line":333},"line",1,[330,335,337],{"class":336},"sgsFI","{\n",[330,339,341,345],{"class":332,"line":340},2,[330,342,344],{"class":343},"sYu0t","  \"hooks\"",[330,346,347],{"class":336},": {\n",[330,349,351,354],{"class":332,"line":350},3,[330,352,353],{"class":343},"    \"PostToolUse\"",[330,355,356],{"class":336},": [\n",[330,358,360],{"class":332,"line":359},4,[330,361,362],{"class":336},"      {\n",[330,364,366,369,372,376],{"class":332,"line":365},5,[330,367,368],{"class":343},"        \"matcher\"",[330,370,371],{"class":336},": ",[330,373,375],{"class":374},"sYBdl","\"Edit|Write|MultiEdit\"",[330,377,378],{"class":336},",\n",[330,380,382,385],{"class":332,"line":381},6,[330,383,384],{"class":343},"        \"hooks\"",[330,386,356],{"class":336},[330,388,390],{"class":332,"line":389},7,[330,391,392],{"class":336},"          {\n",[330,394,396,399,401,404],{"class":332,"line":395},8,[330,397,398],{"class":343},"            \"type\"",[330,400,371],{"class":336},[330,402,403],{"class":374},"\"command\"",[330,405,378],{"class":336},[330,407,409,412,414,417,420,423,426,429,431,434,436,439],{"class":332,"line":408},9,[330,410,411],{"class":343},"            \"command\"",[330,413,371],{"class":336},[330,415,416],{"class":374},"\"echo ",[330,418,419],{"class":343},"\\\"",[330,421,422],{"class":374},"[hook] $(date) fired on $(echo ",[330,424,425],{"class":343},"\\\\\\\"",[330,427,428],{"class":374},"$CLAUDE_TOOL_NAME",[330,430,425],{"class":343},[330,432,433],{"class":374},")",[330,435,419],{"class":343},[330,437,438],{"class":374}," >> \u002Ftmp\u002Fclaude-hook.log\"",[330,440,378],{"class":336},[330,442,444,447,449],{"class":332,"line":443},10,[330,445,446],{"class":343},"            \"timeout\"",[330,448,371],{"class":336},[330,450,451],{"class":343},"5\n",[330,453,455],{"class":332,"line":454},11,[330,456,457],{"class":336},"          }\n",[330,459,461],{"class":332,"line":460},12,[330,462,463],{"class":336},"        ]\n",[330,465,467],{"class":332,"line":466},13,[330,468,469],{"class":336},"      }\n",[330,471,473],{"class":332,"line":472},14,[330,474,475],{"class":336},"    ]\n",[330,477,479],{"class":332,"line":478},15,[330,480,481],{"class":336},"  }\n",[330,483,485],{"class":332,"line":484},16,[330,486,487],{"class":336},"}\n",[11,489,490],{},"Trigger an edit. Then:",[97,492,496],{"className":493,"code":494,"language":495,"meta":104,"style":104},"language-bash shiki shiki-themes github-light","tail -f \u002Ftmp\u002Fclaude-hook.log\n","bash",[46,497,498],{"__ignoreMap":104},[330,499,500,504,507],{"class":332,"line":333},[330,501,503],{"class":502},"s7eDp","tail",[330,505,506],{"class":343}," -f",[330,508,509],{"class":374}," \u002Ftmp\u002Fclaude-hook.log\n",[511,512,513,519],"ul",{},[35,514,515,518],{},[22,516,517],{},"Log appears with every edit"," → plumbing works, your real hook has a bug inside it.",[35,520,521,524,525,528],{},[22,522,523],{},"Log is empty"," → the settings aren't being loaded. Validate JSON: ",[46,526,527],{},"jq . .claude\u002Fsettings.json",". Confirm the file path.",[27,530,126],{"id":531},"prevention-1",[11,533,534,535,538,539,85],{},"Always end real hook commands with an explicit exit code and an ",[46,536,537],{},"echo"," you can grep for. A hook that fails silently is worse than no hook — you'll trust a gate that isn't there. See ",[137,540,542],{"href":541},"\u002Fextensions#hooks","Extensions → Hooks",[15,544,547,556,559,609,613,668,671,714,718,808,827,830],{"id":545,"title":546},"mcp","MCP Won't Connect",[11,548,549,551,552,555],{},[22,550,24],{}," — MCP tools don't appear in Claude's tool list. Or ",[46,553,554],{},"claude mcp list"," shows the server as failed. Or you get a timeout when Claude tries to call an MCP tool.",[27,557,158],{"id":558},"likely-causes-2",[32,560,561,574,587,597,603],{},[35,562,563,63,566,569,570,573],{},[22,564,565],{},"The command can't be found.",[46,567,568],{},"npx -y …"," is usually fine, but ",[46,571,572],{},"python -m something"," fails if you're in the wrong venv.",[35,575,576,63,579,582,583,586],{},[22,577,578],{},"Env var interpolation wrong.",[46,580,581],{},"\"${env:API_KEY}\""," requires the env var to be set in the parent shell before ",[46,584,585],{},"claude"," starts.",[35,588,589,592,593,596],{},[22,590,591],{},"Package not installed yet."," First ",[46,594,595],{},"npx -y"," run downloads; it can exceed the startup timeout.",[35,598,599,602],{},[22,600,601],{},"STDIO vs HTTP confusion."," Server is built for one transport, you configured the other.",[35,604,605,608],{},[22,606,607],{},"Working directory mismatch."," Server uses relative paths; Claude starts it from a different cwd than you tested.",[27,610,612],{"id":611},"fix-run-the-server-manually-first","Fix — run the server manually first",[97,614,617],{"className":493,"code":615,"filename":616,"language":495,"meta":104,"style":104},"# Grab the exact command from .mcp.json\ncat .mcp.json | jq '.mcpServers[\"\u003Cserver-name>\"]'\n\n# Run it yourself, in the same shell you start `claude` from\nnpx -y @modelcontextprotocol\u002Fserver-postgres postgresql:\u002F\u002Flocalhost:5432\u002Fdev\n","reproduce outside claude",[46,618,619,625,643,649,654],{"__ignoreMap":104},[330,620,621],{"class":332,"line":333},[330,622,624],{"class":623},"sAwPA","# Grab the exact command from .mcp.json\n",[330,626,627,630,633,637,640],{"class":332,"line":340},[330,628,629],{"class":502},"cat",[330,631,632],{"class":374}," .mcp.json",[330,634,636],{"class":635},"sD7c4"," |",[330,638,639],{"class":502}," jq",[330,641,642],{"class":374}," '.mcpServers[\"\u003Cserver-name>\"]'\n",[330,644,645],{"class":332,"line":350},[330,646,648],{"emptyLinePlaceholder":647},true,"\n",[330,650,651],{"class":332,"line":359},[330,652,653],{"class":623},"# Run it yourself, in the same shell you start `claude` from\n",[330,655,656,659,662,665],{"class":332,"line":365},[330,657,658],{"class":502},"npx",[330,660,661],{"class":343}," -y",[330,663,664],{"class":374}," @modelcontextprotocol\u002Fserver-postgres",[330,666,667],{"class":374}," postgresql:\u002F\u002Flocalhost:5432\u002Fdev\n",[11,669,670],{},"If the manual run prints errors, fix those — Claude was swallowing them. If the manual run works but Claude still fails:",[97,672,675],{"className":493,"code":673,"filename":674,"language":495,"meta":104,"style":104},"claude mcp list         # see status\nclaude mcp test \u003Cname>  # invoke a no-op call (if supported in your version)\n","ask claude to test it",[46,676,677,690],{"__ignoreMap":104},[330,678,679,681,684,687],{"class":332,"line":333},[330,680,585],{"class":502},[330,682,683],{"class":374}," mcp",[330,685,686],{"class":374}," list",[330,688,689],{"class":623},"         # see status\n",[330,691,692,694,696,699,702,705,708,711],{"class":332,"line":340},[330,693,585],{"class":502},[330,695,683],{"class":374},[330,697,698],{"class":374}," test",[330,700,701],{"class":635}," \u003C",[330,703,704],{"class":374},"nam",[330,706,707],{"class":336},"e",[330,709,710],{"class":635},">",[330,712,713],{"class":623},"  # invoke a no-op call (if supported in your version)\n",[27,715,717],{"id":716},"common-env-var-fix","Common env-var fix",[97,719,722],{"className":324,"code":720,"filename":721,"language":326,"meta":104,"style":104},"{\n  \"mcpServers\": {\n    \"linear\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol\u002Fserver-linear\"],\n      \"env\": {\n        \"LINEAR_API_KEY\": \"${env:LINEAR_API_KEY}\"\n      }\n    }\n  }\n}\n",".mcp.json — explicit env",[46,723,724,728,735,742,754,774,781,791,795,800,804],{"__ignoreMap":104},[330,725,726],{"class":332,"line":333},[330,727,337],{"class":336},[330,729,730,733],{"class":332,"line":340},[330,731,732],{"class":343},"  \"mcpServers\"",[330,734,347],{"class":336},[330,736,737,740],{"class":332,"line":350},[330,738,739],{"class":343},"    \"linear\"",[330,741,347],{"class":336},[330,743,744,747,749,752],{"class":332,"line":359},[330,745,746],{"class":343},"      \"command\"",[330,748,371],{"class":336},[330,750,751],{"class":374},"\"npx\"",[330,753,378],{"class":336},[330,755,756,759,762,765,768,771],{"class":332,"line":365},[330,757,758],{"class":343},"      \"args\"",[330,760,761],{"class":336},": [",[330,763,764],{"class":374},"\"-y\"",[330,766,767],{"class":336},", ",[330,769,770],{"class":374},"\"@modelcontextprotocol\u002Fserver-linear\"",[330,772,773],{"class":336},"],\n",[330,775,776,779],{"class":332,"line":381},[330,777,778],{"class":343},"      \"env\"",[330,780,347],{"class":336},[330,782,783,786,788],{"class":332,"line":389},[330,784,785],{"class":343},"        \"LINEAR_API_KEY\"",[330,787,371],{"class":336},[330,789,790],{"class":374},"\"${env:LINEAR_API_KEY}\"\n",[330,792,793],{"class":332,"line":395},[330,794,469],{"class":336},[330,796,797],{"class":332,"line":408},[330,798,799],{"class":336},"    }\n",[330,801,802],{"class":332,"line":443},[330,803,481],{"class":336},[330,805,806],{"class":332,"line":454},[330,807,487],{"class":336},[11,809,810,811,814,815,817,818,821,822,826],{},"Make sure ",[46,812,813],{},"LINEAR_API_KEY"," is exported in your shell before running ",[46,816,585],{},". ",[46,819,820],{},".env"," files loaded by your app are ",[823,824,825],"em",{},"not"," automatically visible to Claude.",[27,828,126],{"id":829},"prevention-2",[11,831,832,833,836],{},"When you add a new MCP server, always test it in a scratch shell before wiring it in. The 10 seconds of ",[46,834,835],{},"npx -y \u003Cserver>"," saves 20 minutes of \"why isn't this working.\"",[15,838,841,850,853,914,918,925,931,967,971,1004,1012],{"id":839,"title":840},"tokens","Tokens Exploding",[11,842,843,845,846,849],{},[22,844,24],{}," — ",[46,847,848],{},"\u002Fcost"," shows a number that makes you wince. Your monthly bill is 3× what you expected. A single feature cost more than a whole week should.",[27,851,158],{"id":852},"likely-causes-3",[32,854,855,870,883,889,898,904],{},[35,856,857,862,863,767,866,869],{},[22,858,859,861],{},[46,860,48],{}," doesn't cover your stack's build outputs."," Claude respects gitignore for searches, so anything gitignored is already hidden — but if ",[46,864,865],{},"dist\u002F",[46,867,868],{},".next\u002F",", or a language-specific cache isn't gitignored, Claude reads it. Tens of thousands of wasted tokens per session.",[35,871,872,878,879,882],{},[22,873,874,877],{},[46,875,876],{},"CLAUDE.md"," is 15K tokens."," It loads ",[823,880,881],{},"every session",", so every session pays the tax before you've typed anything.",[35,884,885,888],{},[22,886,887],{},"Tool loop."," Claude called the same thing 40 times because each result pointed back to the same missing dependency.",[35,890,891,894,895,897],{},[22,892,893],{},"Huge file reads."," A single ",[46,896,115],{}," on a 5K-line file is 15K tokens. Multiply by 10 reads.",[35,899,900,903],{},[22,901,902],{},"Runaway subagents."," Subagents doing deep exploration with no budget.",[35,905,906,909,910,85],{},[22,907,908],{},"Sonnet\u002FOpus for work Haiku could do."," Routing decisions compound — see ",[137,911,913],{"href":912},"\u002Ftokens#routing","Tokens → Model Routing",[27,915,917],{"id":916},"fix-the-5-minute-audit","Fix — the 5-minute audit",[97,919,923],{"className":920,"code":921,"filename":922,"language":103,"meta":104},[100],"\u002Fcontext   # see the breakdown — system prompt, CLAUDE.md, tools, files, convo\n\u002Fcost      # total tokens used this session + $ spent\n","diagnostic",[46,924,921],{"__ignoreMap":104},[11,926,927,928,930],{},"Look at ",[46,929,153],{},":",[511,932,933,939,949,957],{},[35,934,935,938],{},[22,936,937],{},"System + tools > 50K"," → you have too many MCP servers loaded or too many hooks.",[35,940,941,944,945,85],{},[22,942,943],{},"CLAUDE.md > 5K"," → put it on a diet. See ",[137,946,948],{"href":947},"\u002Ftokens#diet","Tokens → CLAUDE.md Diet",[35,950,951,954,955,85],{},[22,952,953],{},"Conversation > 100K"," → you're in a marathon session; hand off per ",[137,956,217],{"href":216},[35,958,959,962,963,966],{},[22,960,961],{},"Files > 30K and you didn't ask for that"," → a path Claude read that should've been gitignored, or a large committed file that needs ",[46,964,965],{},"Read(...)"," denied.",[27,968,970],{"id":969},"the-three-highest-leverage-fixes","The three highest-leverage fixes",[32,972,973,995,1001],{},[35,974,975,976,978,979,767,982,984,985,988,989,992,993,85],{},"Audit your ",[46,977,48],{},". Make sure ",[46,980,981],{},"node_modules\u002F",[46,983,865],{},", build artifacts, and ",[46,986,987],{},".cache\u002F"," are in it. Claude respects it for searches, and that recovers 20–40K tokens in most repos. For committed-but-oversized paths, add a ",[46,990,991],{},"Read(.\u002Fpath\u002F**)"," to ",[46,994,52],{},[35,996,997,998,1000],{},"Halve your ",[46,999,876],{},". Every token there pays interest on every session.",[35,1002,1003],{},"Route routine tasks to Haiku. Subagents especially.",[11,1005,1006,1007,1011],{},"See ",[137,1008,1010],{"href":1009},"\u002Ftokens#three-fixes","Tokens → The 3 Fixes"," for the full version.",[227,1013,1016],{"title":1014,"variant":1015},"The 24-hour rule","tip",[11,1017,1018],{},"If a CLAUDE.md entry hasn't saved you from a mistake in the last 24 hours of work, it's probably not worth its tokens. Audit quarterly.",[15,1020,1023,1031,1034,1060,1064,1083,1086,1106,1110,1113,1161,1164],{"id":1021,"title":1022},"rate-limits","Rate Limits",[11,1024,1025,845,1027,1030],{},[22,1026,24],{},[46,1028,1029],{},"429"," errors, \"please slow down\" messages, or requests hanging and then failing. Happens most often when multiple parallel agents fire at once.",[27,1032,158],{"id":1033},"likely-causes-4",[32,1035,1036,1042,1048,1054],{},[35,1037,1038,1041],{},[22,1039,1040],{},"Your plan's per-minute or daily limit."," Pro \u002F Team \u002F Enterprise all have different caps. Team accounts are pooled.",[35,1043,1044,1047],{},[22,1045,1046],{},"Burst parallelism."," Three worktrees firing Best-of-N simultaneously → nine concurrent Claude calls → 429.",[35,1049,1050,1053],{},[22,1051,1052],{},"An MCP or hook is hammering the API."," Not you directly — a hook that calls Claude on every file edit.",[35,1055,1056,1059],{},[22,1057,1058],{},"Model tier."," Opus has stricter per-minute caps than Sonnet or Haiku.",[27,1061,1063],{"id":1062},"fix-in-order","Fix — in order",[97,1065,1068],{"className":493,"code":1066,"filename":1067,"language":495,"meta":104,"style":104},"# The dashboard is the source of truth\nopen https:\u002F\u002Fconsole.anthropic.com\u002Fusage\n","check your plan",[46,1069,1070,1075],{"__ignoreMap":104},[330,1071,1072],{"class":332,"line":333},[330,1073,1074],{"class":623},"# The dashboard is the source of truth\n",[330,1076,1077,1080],{"class":332,"line":340},[330,1078,1079],{"class":502},"open",[330,1081,1082],{"class":374}," https:\u002F\u002Fconsole.anthropic.com\u002Fusage\n",[11,1084,1085],{},"Then, depending on cause:",[511,1087,1088,1094,1100],{},[35,1089,1090,1093],{},[22,1091,1092],{},"Parallel agents burst"," → serialize them. Run three agents in sequence via a shell loop instead of three terminals at once.",[35,1095,1096,1099],{},[22,1097,1098],{},"One Opus agent"," → drop it to Sonnet. Most work doesn't need Opus.",[35,1101,1102,1105],{},[22,1103,1104],{},"Recurring hook"," → check if the hook is calling Claude. If so, either disable it during intensive sessions or give it its own lower-tier model.",[27,1107,1109],{"id":1108},"programmatic-backoff","Programmatic backoff",[11,1111,1112],{},"If you're driving Claude via the SDK or a script, implement exponential backoff — not a tight retry loop, which just makes the 429 worse.",[97,1114,1119],{"className":1115,"code":1116,"filename":1117,"language":1118,"meta":104,"style":104},"language-python shiki shiki-themes github-light","import time, random\nfor attempt in range(5):\n    try:\n        return client.messages.create(...)\n    except anthropic.RateLimitError:\n        wait = (2 ** attempt) + random.random()\n        time.sleep(wait)\nraise RuntimeError(\"rate limited 5× in a row\")\n","backoff sketch","python",[46,1120,1121,1126,1131,1136,1141,1146,1151,1156],{"__ignoreMap":104},[330,1122,1123],{"class":332,"line":333},[330,1124,1125],{},"import time, random\n",[330,1127,1128],{"class":332,"line":340},[330,1129,1130],{},"for attempt in range(5):\n",[330,1132,1133],{"class":332,"line":350},[330,1134,1135],{},"    try:\n",[330,1137,1138],{"class":332,"line":359},[330,1139,1140],{},"        return client.messages.create(...)\n",[330,1142,1143],{"class":332,"line":365},[330,1144,1145],{},"    except anthropic.RateLimitError:\n",[330,1147,1148],{"class":332,"line":381},[330,1149,1150],{},"        wait = (2 ** attempt) + random.random()\n",[330,1152,1153],{"class":332,"line":389},[330,1154,1155],{},"        time.sleep(wait)\n",[330,1157,1158],{"class":332,"line":395},[330,1159,1160],{},"raise RuntimeError(\"rate limited 5× in a row\")\n",[27,1162,126],{"id":1163},"prevention-3",[11,1165,1166],{},"If you're running agent teams, put a concurrency cap on the orchestrator: no more than N parallel agents at once, where N is the sustainable limit for your plan. Two is fine for most plans; five is where things get tight; ten and you'll burn through limits inside an hour.",[15,1168,1171,1182,1185,1227,1231,1273,1276,1334,1357,1361,1364,1385,1398,1402,1405,1424],{"id":1169,"title":1170},"auth","Auth & Login Issues",[11,1172,1173,845,1175,1178,1179,1181],{},[22,1174,24],{},[46,1176,1177],{},"401 unauthorized",", \"token expired,\" login redirect loop in the browser, or ",[46,1180,585],{}," starts but can't call the model.",[27,1183,158],{"id":1184},"likely-causes-5",[32,1186,1187,1193,1202,1215,1221],{},[35,1188,1189,1192],{},[22,1190,1191],{},"OAuth token expired."," Most common for users on the Pro\u002FTeam plans.",[35,1194,1195,1198,1199,1201],{},[22,1196,1197],{},"Stale API key."," Rotated on the dashboard, ",[46,1200,820],{}," or shell not updated.",[35,1203,1204,63,1207,1210,1211,1214],{},[22,1205,1206],{},"Two auth sources conflicting.",[46,1208,1209],{},"ANTHROPIC_API_KEY"," in your env ",[823,1212,1213],{},"and"," an OAuth session — Claude picks one, and it might be the wrong one.",[35,1216,1217,1220],{},[22,1218,1219],{},"Wrong account."," You logged into the personal account; the repo expects the work account.",[35,1222,1223,1226],{},[22,1224,1225],{},"Corporate VPN \u002F proxy."," Blocks the OAuth redirect or the API calls.",[27,1228,1230],{"id":1229},"fix-the-reset-sequence","Fix — the reset sequence",[97,1232,1235],{"className":493,"code":1233,"filename":1234,"language":495,"meta":104,"style":104},"claude \u002Flogout       # clears the cached OAuth token\n# clear any stale env vars in the current shell\nunset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN\nclaude \u002Flogin        # fresh browser auth\n","nuclear option, usually works",[46,1236,1237,1247,1252,1263],{"__ignoreMap":104},[330,1238,1239,1241,1244],{"class":332,"line":333},[330,1240,585],{"class":502},[330,1242,1243],{"class":374}," \u002Flogout",[330,1245,1246],{"class":623},"       # clears the cached OAuth token\n",[330,1248,1249],{"class":332,"line":340},[330,1250,1251],{"class":623},"# clear any stale env vars in the current shell\n",[330,1253,1254,1257,1260],{"class":332,"line":350},[330,1255,1256],{"class":343},"unset",[330,1258,1259],{"class":374}," ANTHROPIC_API_KEY",[330,1261,1262],{"class":374}," ANTHROPIC_AUTH_TOKEN\n",[330,1264,1265,1267,1270],{"class":332,"line":359},[330,1266,585],{"class":502},[330,1268,1269],{"class":374}," \u002Flogin",[330,1271,1272],{"class":623},"        # fresh browser auth\n",[11,1274,1275],{},"If you're using an API key (not OAuth):",[97,1277,1280],{"className":493,"code":1278,"filename":1279,"language":495,"meta":104,"style":104},"curl https:\u002F\u002Fapi.anthropic.com\u002Fv1\u002Fmessages \\\n  -H \"x-api-key: $ANTHROPIC_API_KEY\" \\\n  -H \"anthropic-version: 2023-06-01\" \\\n  -H \"content-type: application\u002Fjson\" \\\n  -d '{\"model\":\"claude-haiku-4-5-20251001\",\"max_tokens\":10,\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}'\n","verify the key works",[46,1281,1282,1292,1308,1317,1326],{"__ignoreMap":104},[330,1283,1284,1286,1289],{"class":332,"line":333},[330,1285,181],{"class":502},[330,1287,1288],{"class":374}," https:\u002F\u002Fapi.anthropic.com\u002Fv1\u002Fmessages",[330,1290,1291],{"class":343}," \\\n",[330,1293,1294,1297,1300,1303,1306],{"class":332,"line":340},[330,1295,1296],{"class":343},"  -H",[330,1298,1299],{"class":374}," \"x-api-key: ",[330,1301,1302],{"class":336},"$ANTHROPIC_API_KEY",[330,1304,1305],{"class":374},"\"",[330,1307,1291],{"class":343},[330,1309,1310,1312,1315],{"class":332,"line":350},[330,1311,1296],{"class":343},[330,1313,1314],{"class":374}," \"anthropic-version: 2023-06-01\"",[330,1316,1291],{"class":343},[330,1318,1319,1321,1324],{"class":332,"line":359},[330,1320,1296],{"class":343},[330,1322,1323],{"class":374}," \"content-type: application\u002Fjson\"",[330,1325,1291],{"class":343},[330,1327,1328,1331],{"class":332,"line":365},[330,1329,1330],{"class":343},"  -d",[330,1332,1333],{"class":374}," '{\"model\":\"claude-haiku-4-5-20251001\",\"max_tokens\":10,\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}'\n",[511,1335,1336,1345,1351],{},[35,1337,1338,1341,1342,1344],{},[22,1339,1340],{},"200 OK"," → key works. The problem is in your ",[46,1343,585],{}," config, not the key.",[35,1346,1347,1350],{},[22,1348,1349],{},"401"," → key is wrong or rotated. Generate a fresh one in the console.",[35,1352,1353,1356],{},[22,1354,1355],{},"403"," → key is right, but your account\u002Fplan doesn't allow that model.",[27,1358,1360],{"id":1359},"when-two-auth-sources-conflict","When two auth sources conflict",[11,1362,1363],{},"Check what's set:",[97,1365,1367],{"className":493,"code":1366,"language":495,"meta":104,"style":104},"env | grep -i anthropic\n",[46,1368,1369],{"__ignoreMap":104},[330,1370,1371,1374,1376,1379,1382],{"class":332,"line":333},[330,1372,1373],{"class":502},"env",[330,1375,636],{"class":635},[330,1377,1378],{"class":502}," grep",[330,1380,1381],{"class":343}," -i",[330,1383,1384],{"class":374}," anthropic\n",[11,1386,1387,1388,1390,1391,1393,1394,1397],{},"If both ",[46,1389,1209],{}," and an OAuth session exist, ",[46,1392,585],{}," typically prefers the API key. If you want OAuth to win, ",[46,1395,1396],{},"unset ANTHROPIC_API_KEY"," — or explicitly tell Claude which auth mode to use via its config.",[27,1399,1401],{"id":1400},"corporate-networks","Corporate networks",[11,1403,1404],{},"If the browser-based login never redirects back, you're likely behind a proxy stripping the OAuth callback. Workarounds:",[511,1406,1407,1410,1421],{},[35,1408,1409],{},"Use an API key instead of OAuth (bypasses the redirect entirely).",[35,1411,1412,1413,1416,1417,1420],{},"Add ",[46,1414,1415],{},"api.anthropic.com"," and ",[46,1418,1419],{},"claude.ai"," to your proxy allowlist.",[35,1422,1423],{},"Authenticate from a non-corporate network once, then move back — tokens persist locally.",[227,1425,1428],{"title":1426,"variant":1427},"If none of the above fixes it","info",[11,1429,1430,1433],{},[46,1431,1432],{},"claude doctor"," dumps the full diagnostic: which auth source is active, which config files are loaded, which env vars are set, what version of Claude Code you're on. Run it first when in doubt — it's faster than guessing.",[1435,1436,1437],"style",{},"html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}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 .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sAwPA, html code.shiki .sAwPA{--shiki-default:#6A737D}html pre.shiki code .sD7c4, html code.shiki .sD7c4{--shiki-default:#D73A49}",{"title":104,"searchDepth":340,"depth":340,"links":1439},[1440,1441,1442,1443,1444,1445,1446,1447,1448,1449,1450,1451,1452,1453,1454,1455,1456,1457,1458,1459,1460,1461,1462],{"id":29,"depth":350,"text":30},{"id":94,"depth":350,"text":95},{"id":125,"depth":350,"text":126},{"id":157,"depth":350,"text":158},{"id":191,"depth":350,"text":192},{"id":258,"depth":350,"text":158},{"id":314,"depth":350,"text":315},{"id":531,"depth":350,"text":126},{"id":558,"depth":350,"text":158},{"id":611,"depth":350,"text":612},{"id":716,"depth":350,"text":717},{"id":829,"depth":350,"text":126},{"id":852,"depth":350,"text":158},{"id":916,"depth":350,"text":917},{"id":969,"depth":350,"text":970},{"id":1033,"depth":350,"text":158},{"id":1062,"depth":350,"text":1063},{"id":1108,"depth":350,"text":1109},{"id":1163,"depth":350,"text":126},{"id":1184,"depth":350,"text":158},{"id":1229,"depth":350,"text":1230},{"id":1359,"depth":350,"text":1360},{"id":1400,"depth":350,"text":1401},"The seven failures you'll hit most — invisible files, out-of-context errors, silent hooks, MCP servers that won't start, runaway tokens, rate limits, and auth loops — with the exact fix for each.","10 min","md","When things break","LucideLifeBuoy",null,{},{"title":1471,"path":1472},"Resources","\u002Fresources","\u002Ftroubleshooting",{"title":1475,"path":1476},"Recipes","\u002Frecipes",{"title":1478,"description":1479,"keywords":1480,"proficiencyLevel":1489,"timeRequired":1490},"Troubleshooting — Fixing Claude Code When It Breaks","Concrete fixes for the most common Claude Code failures: invisible files, context blow-ups, hooks that don't fire, MCP server failures, runaway token bills, rate limits, and authentication issues.",[1481,1482,1483,1484,1485,1486,1487,1488],"claude code troubleshooting","claude code errors","mcp server debug","permissions deny","hook didnt fire","rate limit","token spike","claude code login","Intermediate","PT10M",[1492,1493,1494,1495,1496,1497,1498],{"id":17,"title":18,"level":340},{"id":144,"title":145,"level":340},{"id":246,"title":247,"level":340},{"id":545,"title":546,"level":340},{"id":839,"title":840,"level":340},{"id":1021,"title":1022,"level":340},{"id":1169,"title":1170,"level":340},"5OfEmDK6aPB5_MGRaZ68LAC3UJQBa20RUBrCUhTnS6s",1777109529289]