Why Claude Code Stopped Working: A Post-Mortem of Permissions, MCP, and Stale State

Claude Code not working after a previously successful run usually means the visible symptom belongs to configuration, permissions, MCP, authentication, limits, context, or session state. Match the symptom before changing anything: configuration debugging, permission evaluation, and MCP diagnostics lead to different fixes, while login, limit, and context errors have separate recovery paths.

What broke

Claude Code not working is easier to diagnose when you classify the visible failure instead of treating it as one general outage.

A configured feature or instruction disappeared. The usual causes are that the file did not load, loaded from a different location than expected, or was overridden by another file, according to the configuration debugger.
Tool calls were blocked. Permission rules are evaluated as deny, then ask, then allow. The first match decides the result, regardless of specificity, so a broad Bash(aws *) deny can block a call that also matches Bash(aws s3 ls) under an allow rule. The permissions documentation explains that an allow rule cannot carve an exception out of a deny.
An MCP server is missing, failed, or empty. Project servers in .mcp.json require approval; dismissing the prompt leaves the server disabled. Relative paths in command or args can also fail because they resolve from the launch directory rather than the location of .mcp.json. A connected server with zero tools has started but is not returning a tool list. See Debug your configuration.
The session reports a hard stop. Not logged in means the session has no valid credential. Session and weekly limit messages block requests until the displayed reset time, and switching models does not restore access. Prompt is too long means the conversation and attached files exceed the context window. These cases are defined in the error reference.
Instructions changed after compaction. The project-root CLAUDE.md is read again after /compact, but instructions held only in the conversation can disappear. Nested files and path-scoped rules may also remain unloaded until Claude Code reaches matching files. The memory documentation describes that reload behavior.

Why

Permissions

Settings are merged rather than loaded as one isolated file. Managed settings apply first; among the remaining scopes, local settings override project settings, and project settings override user settings. That precedence is why editing an expected file may have no effect while the configuration debugger shows that another scope supplied the effective value.

The active permission mode can also hide the real problem. In dontAsk mode, Claude Code automatically denies calls that would otherwise request approval. bypassPermissions disables prompts and safety checks so calls can execute immediately, including writes to protected paths. Setting bypassPermissions as the default in .claude/settings.json or .claude/settings.local.json does not make it effective; the session starts in Manual mode instead. These distinctions come from the permission mode documentation.

That makes bypassPermissions a poor diagnostic shortcut. It changes the safety boundary rather than repairing a deny rule, an unapproved MCP server, or a bad path.

MCP

An MCP problem can occur at approval, startup, or tool discovery. Dismissing project approval prevents the server from being enabled. A relative executable path may work in one launch directory and fail in another because the path is resolved from the directory where Claude Code was started. Finally, Connected proves less than it appears to: the process can be running while returning no tools.

These states need different checks. Approval does not prove that the command starts, and a started process does not prove that its tool list is available. The MCP troubleshooting guidance keeps those checks separate.

Stale state

Configuration precedence and conversation state can make two sessions that appear identical behave differently. A root instruction file may be reloaded, while a nested file has not been visited or a path-scoped rule has not matched. A setting in a broader scope may also be hidden by a closer project or local override.

We have encountered the same general stale-state pattern in our own setup: an agent judged a script from an outdated header comment, while the routing code showed what it actually did. We now read the executable routing path rather than treating an old summary as current. That is our operating experience, not a claim about Claude Code.

Fix

Start with the read-only diagnostic from your terminal:

claude doctor

It reports installation and settings diagnostics without starting a session and can locate invalid settings files, as documented in Debug your configuration. Use its output to find invalid files, then review the merge order before assuming your edit failed.

For permission problems, open the permission manager inside Claude Code:

/permissions

The dialog lists every permission rule and the settings file that supplied it, according to Configure permissions. If a broad deny is blocking a call you intend to allow, change the owning deny rule rather than expecting a narrower allow to override it. Also check the active mode: dontAsk converts would-be prompts into automatic denials, while bypassPermissions removes prompts and safety checks. Do not infer the active mode from an ineffective project-file setting; the permission mode documentation says such a setting leaves the session in Manual mode.

For MCP, open:

/mcp

Approve the project server if its prompt was dismissed. If the server is marked failed, inspect command and args for relative paths and make sure they resolve from the directory where you launch Claude Code. The documentation identifies the launch directory as the base but does not prescribe one universal cross-platform path syntax.

If the server is connected but exposes zero tools, select Reconnect from /mcp. When the tool list remains empty, run:

claude --debug=mcp

Then read the server’s standard error in:

~/.claude/debug/<session-id>.txt

That escalation path is specified in the MCP diagnostics.

For a login failure with no obvious cause, use the documented clean re-authentication sequence:

/logout

Close Claude Code, restart it with:

claude

Complete authentication again. If the session explicitly reports Not logged in, run:

/login

The re-authentication sequence comes from Troubleshoot installation and login, while the credential requirement comes from the error reference.

A session or weekly limit is different: wait for the reset time shown in the message. The limits are shared across models, so changing models is not a workaround.

For a context-window stop, use either documented interactive recovery command:

/compact

or:

/clear

After /compact, check whether the missing instruction actually exists in the project-root CLAUDE.md. If it existed only in the conversation, in an unloaded nested file, or in a path-scoped rule that did not match, put durable project-wide direction in the root file and keep narrower rules where the memory documentation says they can load.

Guard

Make the checks part of the normal startup path:

Run claude doctor after settings changes, especially when an edit should have taken effect but did not.
Use /permissions before blaming the model. Confirm both the rule order and the settings file supplying each rule.
For MCP-dependent work, confirm project approval, the launch directory used by relative paths, and the actual tool list. Treat Connected as a process signal, not proof that the integration is usable.
Keep durable project-wide instructions in the project-root CLAUDE.md. Expect nested and path-scoped instructions to load only under their documented conditions.
Keep the login, limit, and context recovery paths separate: re-authenticate for unexplained login failures, wait for the stated reset for limits, and compact or clear an oversized context.

In our own agent setup, a forced restart erased scratch files and background child processes, while a command-line login had expired. We now check APIs, repositories, registries, and partially written files before redoing work. Many of our sessions share a working directory, so we also treat the launch directory as part of the runtime context.

The practical guard is read-back. A configuration file existing, an MCP server showing Connected, or an agent reporting success does not establish that the intended instruction loaded or the intended tool worked. Verify the effective setting, returned tool list, or user-visible result before calling the task finished.

Sources