Claude Code troubleshooting

Stuck with Claude Code

Claude going off track, a broken project, a session that crawls, a hook that never fires, usage creeping up: the same things go wrong for almost everyone. Here are the 12 most common situations, what causes them, and the exact move that gets you out.

See the 12 situations

Free to read, taken from the SOS module of Koneetiv Academy.

It is not you, it is a missing habit

When Claude Code goes off track, the cause is rarely mysterious: an instruction that faded, a saturated context, a setting changed without restarting the session. Each situation below is fixed with a single move. And each one is prevented by a simple habit, listed at the end of the card.

Emergency

Take back control

1Claude is heading the wrong way and keeps going: how do I stop it?

WhyYour request left room for several readings and Claude picked one. The further it goes, the deeper it commits to that path.
The fixPress Esc to stop it immediately: the session stays intact. Then redirect with a precise message stating what you expected and what should not have happened. If your files have already changed, /rewind restores the code and/or the conversation.
Interrupt at the first doubt rather than at the end: there is far less to undo.

2I have broken my project: how do I undo what Claude did?

WhyChanges piled up with no intermediate save point. The combined effect is hard to untangle by eye.
The fixNothing is permanent. /rewind, or a double press on Esc, restores an earlier state. If you had asked for a commit before starting, simply say "go back to the last commit".
Make a habit of asking for a commit before any large change.
Quality

Keep Claude on track

3Claude is not following my instructions, it forgets them halfway through

WhyAn instruction given mid conversation dilutes as the exchange grows. It carries no special status compared with the rest of the conversation.
The fixLasting instructions belong in CLAUDE.md, which you open with /memory: they are read again at every session. For something that must apply 100 % of the time, use a hook rather than a written instruction.
The moment an instruction should still hold tomorrow, write it into CLAUDE.md instead of repeating it.

4The session is slow, Claude repeats itself or stops responding

WhyThe context is most likely saturated: the conversation is carrying too much history, and what matters is buried in the rest.
The fixIn Claude Code, /compact summarises the exchange and lightens it while keeping the thread. If you are moving to a new subject, use /clear and start fresh.
Simple rule: one conversation, one task.

12I do not know how to phrase my request to Claude

WhyA vague request leaves Claude making the calls for you. The result is coherent in itself, but beside your actual need.
The fixThe structure that works: the context (where you are, what you are working on), the precise task, the constraints, the expected format.
The most effective shortcut: ask Claude what it needs in order to do this well.
Tooling

Connect and automate

5My hook is not working, it never fires

WhyA hook only fires when the event, the matcher and the session state all line up. Any one of the three being off is enough to keep it silent.
The fixA hook that stays silent comes down to three checks, in this order: 1) the event is the right one, PreToolUse is not PostToolUse; 2) the matcher targets the right tool, for example Write; 3) the session was restarted after the settings were changed.
Always restart the session after touching your settings.

6An MCP connector has stopped responding

WhyA connector usually relies on an authorisation granted to an external service, and an authorisation expires or can be withdrawn on the service side.
The fixOpen /mcp to see the connector status. In most cases the authentication has expired: reconnect. Also check that access has not been revoked on the service side.
When a connector behaves oddly, check /mcp before looking anywhere else.

7Claude asks permission for every single action

WhyThat is the cautious mode, normal at the start: until you have said what you allow, Claude asks for your approval before every action that touches your files or your environment.
The fixTo stop approving every single action, add targeted allow rules for the ones you understand and consider safe. Everything else still goes through a permission request.
Grant permissions as you go, action by action, rather than opening everything at once.

11My artifact will not run, nothing shows up

WhyCreating and running code on claude.ai depends on an option that is not necessarily enabled on your account.
The fixIn your claude.ai settings, under Settings then Features, check that "Code execution & file creation" is enabled. Then explicitly ask for it to be run again.
Check that setting once and for all before concluding your request was the problem.
Usage

Stay in control of your usage

8My response was cut off, or I hit a limit

WhyYou have hit a limit: either your plan's, or the conversation's context window.
The fixA cut off response or a limit reached leaves three options: wait for the next window, use /compact to lighten the conversation, or move simple tasks to a lighter model.
Do not let a conversation grow indefinitely: /clear between tasks.

9Which model should I use: Opus, Sonnet or Haiku?

WhyModels are not equally suited to every task, and keeping the most powerful one on permanently is not always the right call.
The fixComplex or critical work: Opus. Everyday work: Sonnet. Repetitive, simple, high volume: Haiku. You can switch at any time with /model.
Pick the model when you start the task, not once it stalls.

10It is using far too much, I burn through my limit too fast

WhyA long context is read again with every message. A conversation that drags on therefore weighs more and more with each exchange.
The fixTo bring usage down in Claude Code: /clear between tasks, conversations focused on a single subject, and the right model for the right job. /cost shows you where the usage goes.
Open /cost now and then: you will quickly see which habits weigh the most.
Prevention

Five habits that prevent most of these situations

None of them require particular technical skill. They become second nature quickly and cover the vast majority of what goes wrong.

Ask for a commit before any large change: you always have a point to return to.
One conversation, one task. /clear when you change subject, /compact when the session gets heavy.
Anything that should still hold tomorrow goes into CLAUDE.md, not a message. Anything that must be automatic goes into a hook.
Press Esc the moment the direction looks wrong: never let it run on hoping it lands right.
Give the context, the task, the constraints and the expected format. When in doubt, ask Claude what is missing.
SOS module

These 12 situations are a module of Koneetiv Academy

Koneetiv Academy is our training platform, free to access. It includes an SOS module that walks through these situations one by one: you describe what is happening, the module gives you the move to make and prepares a ready formatted request, which you paste into your own Claude account to unblock the situation in your own context.

Open Koneetiv Academy
Frequently asked

What people ask us most

What exactly is Claude Code?
It is one of the surfaces of Claude, the one that works in your terminal and directly on the files of your project. It sits alongside other surfaces, such as the Claude app and the developer platform. So it is not a separate product, but a way of using Claude as close as possible to your working environment.
Do I need to know how to code to use it?
No. You write your requests in plain language and Claude handles the technical side. What matters is describing precisely what you want, and knowing the few safety habits on this page: ask for a commit before a large change, interrupt with Esc, go back with /rewind.
Does it work in languages other than English?
Yes. You can phrase your requests and write your lasting instructions in CLAUDE.md in your own language. Only the command names stay as they are: /rewind, /compact, /clear, /mcp, /model, /cost, /memory.
Where should I start if I have never used Claude Code?
Start with a real project that carries no risk, and one task at a time: it is the fastest way to see what Claude actually does with your requests. Ask for a commit before anything important, keep conversations short, and use /clear as soon as you change subject. Two or three working rules written into CLAUDE.md are enough to begin with, and you will add to them as you go. Koneetiv Academy takes you through that path step by step, free of charge.
Koneetiv Academy
Do your teams want to learn how to use Claude?

Our online training platform is free: 4 tracks, 18 modules, 54 lessons and a certification path. The first lesson runs without creating an account.

Explore Koneetiv Academy

Get unstuck, then get ahead

The SOS module handles the emergency. The rest of the training keeps you out of it. Free, with no technical prerequisites.

Talk to a Koneetiv expert