Claude Code stuck on thinking: what to check, in order

Which kind of stuck do you have?

Name the shape before you touch anything, because the four have different answers and one of them is to keep waiting. Pick the line closest to what is on your screen.

• Nothing has moved for a few minutes and I want to know whether it is working
• A turn produced nothing at all, and there is no error either
• I do not care about the cause, I want it moving again
• It says it is compacting and never finishes
• It is still printing, or it nearly finished, or the screen is odd

If your session did print an error, this is the wrong page. The Claude Code error messages guide indexes the messages themselves and is the faster route. If it is sitting before it ever started, that is usually sign-in rather than the model, and the sign-in guide covers it.

What the timers do and do not cover

Claude Code watches a streaming response with four independent timers, and their purpose is the one you want here: a connection that goes quiet should fail and retry rather than hang.

One boundary is worth knowing before you start timing anything. API_TIMEOUT_MS is the time each attempt has to receive its response headers, and Anthropic's own entry for it says that it does not limit how long a streaming response runs afterwards. Past the headers, a reply is bounded by the stream watchdogs and by nothing else.

Those watchdogs do still bound it, and a watchdog firing is never silent. When one aborts a stalled stream, Claude Code treats it as a mid-stream failure and you get one of three things depending on how far the reply had got: a retry, a turn that ends with an error, or a turn that ends normally with an incomplete-response notice and the text written so far kept. What keep-alive traffic buys a stalled stream is time rather than escape, because the watchdog it resets only tolerates that for so long.

So the timers do end a dead connection, eventually. What none of them can see is a turn that never became a request, or a process that stopped reading its input: there is no stream for a watchdog to watch, so nothing fires and nothing arrives. That is the shape the rest of this page is about, and the next section puts a number on the other one so this one becomes visible by elimination.

How long the wait should be

Before you time anything, look at the line under the spinner. It is the one part of this screen that names the shape instead of hinting at it. While Claude Code is retrying a request, the spinner shows a Retrying in Ns · attempt x/y countdown after an error label. If no data arrives on the response stream for 20 seconds while a request is still pending, it shows Waiting for API response · will retry in … · check your network, and that appears before any retry has started, because the request has not failed yet. Behind a gateway the threshold is 45 seconds on v2.1.309 or later. Both banners clear on their own when data resumes or a retry succeeds.

Both of those belong to a request that exists. A turn that never became one, and a process that has stopped reading its input, produce neither: there is no countdown, no error label, and no line to read. That absence is the useful signal, and it is why the spinner alone proves so little.

The table shows the four timers with their defaults on the direct Anthropic API. Which of them run depends on your provider, and the paragraph under the table says how.

Which timers you actually have is a provider question. The event-level watchdog runs on every provider. The first-byte deadline does not run through a gateway, or on Google Cloud's Agent Platform or Microsoft Foundry, and it is opt-in on Amazon Bedrock. The body idle timeout covers providers other than the direct API, Claude Platform on AWS, and Bedrock with the byte watchdog enabled.

The event-level watchdog is the loose one, and it explains the longest waits. Bytes arriving on the connection reset it, including keep-alive pings, though only for a limited time without a parsed event, so a stream that is alive but saying nothing stretches the wait past the number in the table rather than escaping it.

These are defaults, not constants. CLAUDE_STREAM_IDLE_TIMEOUT_MS sets both watchdogs' timeout and is raised to 5 minutes if you set it lower, with a 30-minute cap on the byte-level one. API_TIMEOUT_MS=0 removes the header limit on v2.1.305 or later. API_FORCE_IDLE_TIMEOUT=0 turns the body idle timeout off. If any of those has been changed on your setup, or by a wrapper around it, then no error yet proves nothing and the table above does not describe your machine.

What the wait looks like when it does end

API Error: No response from API (waited 3m, then 10m on the retry). If a proxy or gateway on your network holds responses until they complete, raise API_TIMEOUT_MS or CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS to wait longer.

Claude Code sent a streaming request and got no response headers inside the first-byte deadline. It aborts rather than wait out the full request timeout, sends the request again if the retry budget allows, and when the retry misses its deadline too the turn ends with this line, which names how long each attempt waited. The first attempt waits for CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS when you set it to 1 or more, clamped to between 10 seconds and 30 minutes. The retry waits one second less than API_TIMEOUT_MS, which is just under 10 minutes by default.

Retries are the other reason a wait runs long. Claude Code retries a failed request 10 times by default, with a cap of 15 as of v2.1.186. Set CLAUDE_CODE_RETRY_WATCHDOG=1 and 429 and 529 capacity errors are retried indefinitely instead, backing off up to 5 minutes between attempts or until the limit resets. On v2.1.199 or later that variable also raises the retry count for server errors, timeouts and dropped connections to 300, which is roughly three hours of backoff. A session in that state is not stuck. It is waiting out a limit, and with the watchdog on and no maximum wait configured, that wait has no limit of its own; it ends when capacity returns or the limit resets.

If the session still accepts a command, /status is worth running: it opens the Status tab with the version, model, account and connectivity, and it works while Claude is responding. A session that will not take a command at all is the shape below.

What other people's long waits ended in

Three open reports are worth reading for the shapes rather than the numbers, and none of them is Anthropic's diagnosis. Issue 98032, filed 2026-09-29, describes turns on one Mac that got no response and then failed after about 6 minutes with a dropped connection, 22 of 26 measured turns landing within seconds of the same point, and the session then showing a retry countdown. Issue 99751, filed 2026-10-05, describes the Claude Desktop Code tab hanging about 7.5 minutes and then failing with ECONNREFUSED, while the same bundled binary run directly worked on its own. Issue 99331, filed 2026-10-03, is the different one: on FreeBSD through Linuxulator the process hung after about 5 minutes and then died in the background with no error shown at all.

Getting it moving without losing the work

The documented order is short. Press Ctrl+C to attempt to cancel the current operation. If the session stays unresponsive, close the terminal and restart it. Anthropic's own note is that restarting does not lose your conversation, and the way back in is to resume it in the same directory:

claude --resume

Ctrl+C is a cancel attempt, not a process kill and not a conversation wipe. The transcript belongs to the session, so the resume above picks it up where it stopped even though the process that was holding it is gone. At an empty prompt the same key does something different: the first press clears whatever you had typed and a second press exits Claude Code, so press it once if you are trying to stop a turn rather than leave.

If it hangs again in the same place, run /doctor inside Claude Code. It checks the installation, settings, extensions and context usage and proposes fixes that it applies after you confirm. When claude will not start at all, the same checkup runs from your shell as claude doctor.

A hang that only appears in one project is worth a clean test. claude --safe-mode disables every customization for that session. If the trouble goes away, the cause is a plugin, an MCP server or a hook rather than Claude Code itself.

Watch for the memory warning as well. Once a session's heap passes 2.5GB, Claude Code says so, and the documented way out is to restart and run claude --continue, which resumes the conversation in a fresh process and hands the memory back.

Stuck on compacting

One stated failure reads as a stall and is worth recognising, because the fix is not to wait: Autocompact is thrashing: the context refilled to the limit... means compaction worked and a file or tool output refilled the window straight away several times, so Claude Code stopped retrying rather than spend API calls on a loop. That one tells you what happened, and a separate guide covers its recovery.

The harder case is the one that prints nothing: a session that says it is compacting, shows no completion line, and never moves again. It has no message of its own, so the recovery order above is the only move available to you, and any advice about context sizes is a guess until the session is running again.

The shapes that only look stuck

Some frozen screens are work being done. Check these before you cancel anything.

• A session that is resuming with a very large table in it. Before v2.1.208, Claude Code rendered every row, and re-rendering could stall the resume. A table over 200 rows now shows its first 200 with a count of the rest, so an older release is the one to suspect.
• A turn whose label has reached its last stage and then holds. The label is progress text, not a promise: compare the elapsed time against the windows above, and treat a wait that outlives them as the no-reply shape.
• A reply that is printing, but printing the same thing. Issue 102886, filed 2026-10-16, reports a response stuck printing break tags without stopping. Movement is not progress, and this one only ends when you stop it.
• Text that stopped mid-sentence. A cut-off reply is what a watchdog abort leaves behind when the answer had already started, and the recovery order applies.

One rule covers all four: a silence the timers will end always ends with something to read. So let the windows in the table above pass first. Once they have and there is still no message, you are not waiting on a timer, and the recovery order is the next move.

Omniscio and the wedge it catches

Omniscio is the desktop app we make for running many Claude Code sessions at once. It belongs on this page because one of those shapes is a process that has stopped reading its input, and nothing watching the connection can see that. Our own product page for it is the auto-restart stuck sessions entry in the docs library.

The watchdog adds a 6-minute ceiling on a turn whose process is alive but has produced no output, a second clock that transcript activity cannot reset. The ordinary first-output wait is 2 minutes on an idle machine and walks up to that same 6 minutes while the machine is busy, so the second clock is what still catches a session whose transcript keeps the first one looking fresh. On a machine that stays saturated, that first-output timeout can be deferred past 6 minutes for up to 60 checks, roughly ten more minutes, so an overloaded machine is not cut off early. The 6-minute ceiling for a session that looks busy but produces nothing is never deferred, which is how it catches a wedge whose transcript keeps the silence timer from firing.

A session counts as wedged only when three things hold together. It is the agent's turn and no first output has arrived, it is past that 6-minute ceiling, and the silence timer is still under budget, which is the signature of something keeping it warm while nothing is being produced. A slow first token never reaches the third condition, because real silence trips the ordinary timeout first.

When it fires, the session gets a short note, the child process is ended, and the turn is restarted. The setting behind that is autoRestartUnresponsiveSessions, on by default, labelled Auto-Restart Stuck Sessions under Settings, Sessions, When sessions stall. With it off, the fake thinking is still stopped, but the session is handed to you as Needs You and your next message restarts it.

Compaction gets its own recovery, and it is separate from that setting. A session that said it was compacting and never said it finished is relaunched rather than nudged, at most twice in a row, with the count clearing after 30 quiet minutes, and then parked with a note instead of being retried forever. That is the no-message compaction case from the section above.

A session that is waiting on you, or parked in a declared wait, is never touched, because it is not the agent's turn. Before this watchdog existed the only backstop for a turn that had wedged was a 4-hour absolute turn cap, which is a runaway guard rather than a recovery, and the watchdog is what turns a hang of that scale into minutes.

The features page covers the rest of what the app does with sessions, and the download page has the installers.

Sources

Every timer, every message and every recovery step on this page rests on one of these. The date beside each one is the day we read it.

• Claude Code troubleshooting, for the Ctrl+C and restart recovery and the resume that keeps the conversation. Read October 27, 2026.
• Claude Code troubleshooting, for the auto-compaction thrashing message. Read October 27, 2026.
• Claude Code troubleshooting, for the 2.5GB memory warning, --continue and --safe-mode. Read October 27, 2026.
• Claude Code troubleshooting, for the large-table rendering change and the version it arrived in. Read October 27, 2026.
• Network configuration, for the four streaming watchdogs, their defaults, and what an abort leaves on screen. Read October 27, 2026.
• Claude Code error reference, for the no-response message, the first attempt and retry waits, and how each is configured. Read October 27, 2026.
• Environment variables, for API_TIMEOUT_MS, CLAUDE_STREAM_IDLE_TIMEOUT_MS, CLAUDE_CODE_MAX_RETRIES, CLAUDE_CODE_RETRY_WATCHDOG and API_FORCE_IDLE_TIMEOUT. Read October 27, 2026.
• Commands reference, for /status, /doctor, /compact and /context. Read October 27, 2026.
• GitHub issues 99331, 98032, 99751 and 102886, all open, for the four waits and loops described above, read through the API with each one's state, date and counts. Read October 27, 2026.
• Auto-restart stuck sessions, our own documentation for the watchdog this page ends on. Read October 27, 2026.

Anthropic's troubleshooting page, its error reference and its environment variable list all move with nearly every Claude Code release, and the network page already carries version notes where a timer changed. Read them again before you trust a copy of this page from a few months back.

Common questions

How long should I wait before deciding Claude Code is stuck?

With no response headers at all, the first attempt gives up after about three minutes, longer on a very large conversation, and the retry after just under ten. A stream that started and then stalled can take longer, but it shows a waiting or retrying banner while it does. A silence with no banner and no message is not one the timers will end.

Does Ctrl+C lose the conversation?

No. Ctrl+C attempts to cancel the current operation, and Anthropic's own recovery note says restarting does not lose your conversation. Run claude --resume in the same directory and the session comes back where it stopped. The text already in the conversation is part of that session, not of the process you ended.

Why does a session hang before it starts doing anything?

A turn that never starts is usually failing earlier than the model call, so nothing is generated for the timers to watch. The recovery order on this page still applies, and the sign-in guide covers the shapes that leave a prompt sitting there.

Is a stuck session the same thing as a rate limit?

No, and they read differently once you know what to look for. A rate-limit wait shows a Retrying countdown and, by default, ends in a message: Claude Code retries a failed request and then reports the error. With the retry watchdog switched on it keeps retrying capacity errors instead, backing off up to five minutes between attempts. A stuck session shows neither, which is why the recovery order here starts with deciding which of the two you are in.