Keep using Claude Code and you will get stuck. This chapter is not a dictionary of errors. It is here to give you an order of triage for working down from a symptom to a cause.
With that order in hand, you can place an error message you have never seen before into the right category. The article on the specific fix is something you read afterwards.
What to do before you search the error message
When people get stuck, most of them paste the error message straight into a search box. That works, but almost always three checks first will get you there faster.
If it was, the cause is not the environment but whatever changed just before. A conversation that grew long, a setting you added, a network you switched to.
Every time means a setting or the environment. Now and then means congestion or your connection, and often the cause is not on your side at all.
At startup, the moment you sent the instruction, or partway through the response? Where it stopped very nearly decides the category.
CHECK 3 does the most work. Once you know where in the gather → act → verify loop from Chapter 1 it stopped, the candidates narrow fast.
Sorting it into one of five categories
Claude Code errors fall into five groups, by where the cause sits. Decide which one you are in first.
Does it start?
No → a problem with the app itself (see the extra below)
Yes
↓
Can you send an instruction?
No, it refuses → 1. Authentication
Yes
↓
Does a response come back?
No, nothing arrives / it cuts off → 2. Connection
It says "limit" → 3. Usage limits
It says "too long" → 4. Context
Yes
↓
It fails whenever an external tool is involved → 5. Tools and extensions
Use this branching to place your bet, then go to the matching section below. Each category has its own shape of fix, so mixing them together is how you lose an afternoon.
1. Authentication — it will not accept who you are
The symptom is being told you are not logged in, or being refused because your credentials are invalid. The giveaway is that it stops before your instruction goes anywhere.
An expired session / being signed in as a different account / mixing up an API key with a subscription / a corporate network blocking the auth traffic
Sign in again → check which account you are signed in as → try a different connection (a phone hotspot, say). If the third one fixes it, you are in category 2
Because signing in again fixes this category so often, it is also the category people keep digging at when it does not. Try twice, and if it is still broken, suspect category 2. Authentication traffic goes over the network too.
2. Connection — nothing arrives, or it cuts off
This is the most misread category. It is not necessarily your configuration that is wrong.
The symptoms split three ways.
A proxy, TLS, or a corporate network blocking the way. This is an environment problem, and a different connection isolates it.
The service is busy. Waiting is the right answer, and fiddling with settings leaves you nothing but side effects.
The connection drops in the middle of a long response. Breaking the output into shorter pieces sometimes stops it happening.
Each has its own article: fixing network, proxy, and TLS errors, 529 Overloaded and 500 errors, and Connection closed mid-response.
Do not try to fix congestion with configuration. If you change ten settings while trying to reproduce something that only fails now and then, you will never know whether you fixed it or time did. Wait a while and retry first, and find out whether it happens every time.
3. Usage limits — you have used up the allowance
This is the category where you are told you have hit a limit. It is not an error but the design, so what you fix is how you use it, not a setting.
The thing to grasp here is that there is more than one allowance. A shorter-cycle allowance and a longer-cycle one exist separately. One can recover while the other is still spent, and you stay blocked. "It came back a moment ago and now it has stopped again" is usually this.
The details are in fixing usage limit reached and, for the weekly allowance measured in practice, the truth about the weekly limit resetting early. Reducing the consumption itself is Chapter 7.
4. Context — the input is too long
This is the category where you are refused for being too long. Think of it as the context window discussion from Chapter 1 showing up as a symptom.
Fold the history up, or cut it off and start fresh. Folding at a break in the work is the default.
Do not paste an enormous file or log wholesale. Hand over only the relevant part, or let it go find it.
The fix for the symptom is in Prompt is too long: causes and fixes, and the judgment about when to fold is in Should you run /compact on a schedule?.
Note that output can also be stopped for violating policy. That is not a length problem, so do not confuse the two. It is a different shape of thing.
5. Tools and extensions — what you plugged in does not work
This is the category that shows up after you add an MCP server or an external tool. The triage is easy: see whether removing it fixes things.
Turn off every extension
→ fixed : the extensions are the cause. Put them back one at a time to find the culprit
→ not fixed : the extensions are irrelevant. Go back to 1-4
Once you know an extension is the cause, go to MCP connection errors: causes and fixes. Almost always it is the format of the config, the path in the launch command, or permissions.
What you should not do here is doubt how clever Claude is. If an extension is not connected, Claude behaves as though that tool does not exist. "I told it to and it will not do it" turning out to be a connection problem is a common story.
An extra — the app itself will not start
If you are using the desktop app rather than the terminal version, it can stop before it ever reaches Claude Code. That is none of the five categories, so it sits outside the triage chart.
The kind that needs repairing on Windows is in Can't open this app: repairing Claude Desktop on Windows, and the kind that freezes around rendering is in why GPU process gone freezes it, and the fix.
Five moves for when you are still stuck
For when you cannot tell the category, or you can and it still is not fixed. Try these from the top down. They are ordered cheapest first.
Trouble that came from context disappears with this. The cheapest move there is.
Congestion and limits resolve on this alone. Do not touch the settings.
If this fixes it, the cause is confirmed as the network on your side.
The triage for category 5. Put them back one at a time. All at once tells you nothing.
Try the same thing in an empty directory. If it does not reproduce, the cause is in the project.
Change one thing at a time. Being stuck makes you want to change several things at once, but then you end up never knowing which one worked, and the next time the same symptom appears you start again from nothing. Pinning down the one move that worked is enormously cheaper in the long run.
If you would rather look things up by the error message itself, common errors and how to fix them works as an index.
Summary
- Before searching the error message, check three things: was it working a minute ago, does it happen every time, and where did it stop
- Causes fall into five categories: authentication, connection, usage limits, context, and tools. Do not mix them while testing
- For congestion and limits, waiting is the right answer. Fiddling with settings leaves nothing but side effects
- There is more than one allowance. A shorter cycle and a longer cycle run separately, so it can come back and then stop again
- The tools category is triaged in one shot by whether removing everything fixes it. Put them back one at a time
- When you are stuck, five moves in order of cost. And change one thing at a time
Once you can get yourself unstuck, the next job is deciding how far to delegate. Move on to Chapter 5, "Permissions and Safety".