If you keep doing AI coding, you will run into errors — it's inevitable. The moment red text appears, your hands freeze, and that frozen time is the biggest enemy of productivity. But don't worry. The errors you meet with Claude Code and other AI coding tools are mostly the same patterns, repeated over and over. Once you can tell which type you're facing, the fix is almost mechanical. This chapter is the trouble-triage map you open first whenever you get stuck.
Become someone errors can't stop
🧭 One summary article first. A cross-cutting roundup of the most common errors is "Claude Code: Common Errors and Fixes — A Roundup". This chapter is the map that gives you an overview of each category; the linked individual articles carry concrete message examples and step-by-step fixes. Bookmark it and start here whenever you get stuck.
Sort errors by "type" first
The first step in fixing anything is telling what kind of error it is. When the layer of the cause differs, so does the place you fix it. Before you dig into the fine details of the message, first match it to one of the following 6 categories. The moment you do, 80% of the fix is decided.
It won't start at all, or the command is missing. A problem at the entrance. ↓ details
You can't log in, or your session expires. The connection to your account. ↓ details
Communication fails, or the server is overloaded. A problem in the route or on the server side. ↓ details
You've hit the cap, or you're in a locked-out window. A problem of plan and usage. ↓ details
Too long, too much crammed in. A problem of how much information you passed. ↓ details
An extension or tool call fails. A problem in the surrounding features. ↓ details
💡 The knack for telling them apart. A single keyword in the error text points you at the answer. command not found → 1, authentication / login → 2, connection / network / 529 → 3, usage limit → 4, too long → 5, MCP / tool → 6. Before reading the whole message, hunt for this one word first.
1. Setup & startup — command not found
The first gate is "it just won't start." The install may have failed partway, or your PATH may not be set, so typing the command gets no response. Getting stuck here means you can't move forward at all, so calmly check the entrance.
Symptom: Typing claude returns "no such command."
Cause: The install location isn't on your PATH, the shell hasn't been reloaded, or the install itself never finished.
Fix: Reopen the terminal / check your PATH / reinstall. Try these in order and you'll usually get through.
Symptom: The install stops with an error / it's blocked by a permission issue.
Cause: An outdated Node.js version, insufficient permissions, or a failed package download over the network.
Fix: Update the prerequisites (Node, etc.) and reconsider admin privileges or the install method. On a corporate network, suspect the proxy too.
🔧 Detailed steps here. How to isolate and actually fix install failures and command not found is covered in "How to Fix command not found / Install Errors." If you stumble on setup, the fastest route is to reinstall exactly as laid out in Chapter 2, "Getting Started with Claude Code."
2. Login & authentication — can't get authorized
This is the pattern where it starts up fine, but you get rejected at login or authentication. It shows up as browser auth not going through, or being suddenly signed out after using it for a while. It's a state where the "handshake" between your account and the tool has slipped.
Symptom: You can't get past the login screen / you're rejected with an auth error / the browser for authentication won't open.
Cause: An expired or corrupted auth token, a failed redirect, using the wrong plan or account, or a clock that's out of sync.
Fix: Sign out once and sign back in / clear the saved credentials and re-authenticate / confirm you're on the right account.
What looks like an "auth error" can sometimes just be the wrong plan or the wrong account under contract.
If you juggle multiple accounts, first check which account you're logged into and what kind of plan it is. Mixing a company-issued account with a personal one is a classic trap.
🔑 Detailed steps here. The steps for re-logging-in and re-acquiring a token when auth won't go through are in "How to Fix Login & Authentication Errors." Most cases are solved by signing in again, but if that doesn't fix it, suspect the network side (category 3) too.
3. Connection & network — can't connect / overloaded
Here the cause splits into two — "your side" and "the server side" — so isolating it is crucial. Is your own connection or proxy blocking things, or is the server just temporarily busy? For the former, the basic policy is to fix it yourself; for the latter, it's to wait or lighten the load.
Symptom: You can't connect, it times out, or the connection drops midway.
Cause: A flaky internet connection, blocking by a corporate proxy or firewall, a VPN, or a certificate or DNS problem.
Fix: Try a different connection / turn off the VPN / review the proxy settings. On a company network, ask your admin what's on the allowlist.
Symptom: You get overloaded or a 5xx. It fails even though your setup is correct.
Cause: A temporary server-side spike in load or an outage. It's not your code or your settings.
Fix: Wait a bit and retry / avoid peak hours / check outage info on the status page.
⚠️ A rule of thumb for isolating it. If other sites and services are fine but only the AI tool goes down, it's likely the server side (529/500), and the fix is "wait." If your other traffic is also unstable, it's your side (connection, proxy, VPN). For details, see "Connection, Network, and Proxy Errors" and "What 529 overloaded / 500 Errors Mean and How to Handle Them."
4. Usage limits — you've hit the cap
This isn't an error but a notice that "you've hit your limit, so you can't use it right now." Each plan caps usage per set time period and per week, and once you touch that ceiling it pauses temporarily. Since nothing is broken, the right answer is to adjust with how you use it and which plan you're on rather than trying to "fix" anything.
Symptom: "You've reached your usage limit" appears and you're locked out until a set time.
Cause: You've reached your plan's usage cap. Running big tasks or long conversations in a short span gets you there faster.
Fix: Wait for the reset / split up conversations and use it lightly / reconsider your plan if needed.
Symptom: You hit the cap mid-week / the reset seems to come earlier or later than you expected.
Cause: The weekly quota may work in a way that isn't the calendar week — for instance, counted from your first use.
Fix: Understand exactly how the reset is counted and plan out how you spread your heavy-consumption work.
📊 Limits are almost entirely avoidable with "management." The meaning of the limits and how to think about wait times is in "What to Do When You Hit the Usage Limit," and how the weekly reset is counted is in "How the Weekly Limit's Early Reset Works." Ways to use it so you rarely touch the cap in the first place are covered together in Chapter 7, "Cost and Efficiency."
5. Input & context — too long
There's a limit to how much information (context) the AI can handle at once. When a conversation drags on, or you hand over a huge file whole, it rejects you with "the input is too long." This is a sign of cramming in too much, so the fix is to reduce or break up what you pass.
Symptom: "The input is too long" appears and your instruction isn't executed.
Cause: Accumulated conversation history, loading a huge file or too many files, or pasted logs that are simply too long.
Fix: Trim or summarize the conversation / start a new conversation / pass only the range you need / break the task into smaller pieces.
Symptom: An error occurs in the thinking-related processing and the response is cut off.
Cause: An inconsistency in conversation state, or an internal processing mismatch tangled up with history. More likely in long conversations.
Fix: Start a fresh conversation / split out the exchange in question. Most cases clear up with a refresh.
✂️ "Too long" can be prevented by design. Concrete ways to cut it down are in "How to Fix prompt is too long," and thinking-related glitches are in "How to Handle thinking block Errors." The root remedy is to break tasks into small pieces in the first place, which ties directly into the way of giving instructions covered in Chapter 4, "Asking Well."
6. MCP & tools — extensions aren't working
With MCP (external tool integration) and tool calls, Claude Code itself can be perfectly fine while just the surrounding extension fails. The knack is to think of it separately from errors in the core. First check "does it still reproduce with the extension removed?" and the isolation moves along fast.
Symptom: You can't connect to the MCP server / integrated tools don't appear in the list or don't respond.
Cause: A mistake in the config file, the server failing to start, a missing path or dependency, or incomplete credentials.
Fix: Review the config / verify the server starts on its own / remove it once and isolate whether the core alone works.
Symptom: A tool call fails / it stalls when passing the call's result back.
Cause: A mismatch in the tool definition or arguments, a slip in conversation state, or a temporary hiccup on the integrated side.
Fix: Reset the conversation / temporarily disable the tool in question to isolate it / check the state of the integration target.
Symptom: A status check around a PR (pull request) errors out.
Cause: Often tangled up with the settings or permissions of the linked CI or checks, or the state of an external service.
Fix: Check the check's settings and permissions / re-run it / check the status of the external service.
🧩 For extensions, "remove and isolate." How to fix MCP connections is in "How to Handle MCP Server Connection Errors," tool-call glitches are in "How to Handle Tool-Call Errors," and PR-check issues are in "How to Handle PR Status-Check Errors." How to use the extension features themselves is covered in Chapter 6, "Using Extensions."
How to get unstuck — the 5 universal moves
Even when you can't pin down the cause right away, there are "universal moves" you should try first. Many errors vanish just by refreshing the state or lightening the load. When none of the categories above gives you a lead, try these five from the top down.
Close the tool and terminal and reopen them. For temporary state glitches, this alone clears most of them. The first move to reach for.
Long conversations are a breeding ground for inconsistency. Start a new conversation, or summarize and tidy the history (the /compact idea) to travel light. Works on category 5.
Don't ask for a lot at once — split the task into small steps. Errors born of "too long" or "too heavy" are avoided at the root this way.
529/500 and congestion are solved by time. Wait a few minutes and rerun. Check the status page for outage info too. Works on categories 3 and 4.
If you truly can't figure it out, hand the whole error text to the AI or a search. Cross-check it with this chapter's roundup article and it usually maps to a known pattern.
🧯 Not panicking is the biggest fix of all. An error isn't a signal that "it's broken" — it's a hint saying "fix this here." Identify the category, try the 5 moves above, and if it still won't budge, go to the individual article. Once this flow becomes second nature, red text won't scare you anymore.
- First, sort the error into 6 categories (setup, auth, connection, usage limits, context, MCP/tools). A single keyword points you at the answer.
- Each category has a near-fixed symptom → cause → fix. For server-side issues like 529/500, "wait," and for too-long input, "split it up, tidy it up."
- Even when the cause is unknown, the 5 universal moves (restart, reset the conversation, break it into small pieces, wait and retry, hand over the error text as-is) get you through most cases.
- For concrete steps, go to the roundup article and each individual article. Limit management is explored deeper in Chapter 7, extensions in Chapter 6.
Once you know how to get along with errors, AI coding surges forward. Next, it's time to expand Claude Code's very capabilities. In the next chapter — Chapter 6, "Using Extensions" — let's make your partner even stronger with hooks, plugins, subagents, and MCP.