Try free

Last updated 13 October 2026

Handle read-only file errors in Claude

The agent stops when it cannot write to files

When you run the command claude in a project directory, the agent begins its work by reading the files you specify. It uses the Read tool to pull content into its context window. Problems arise when the agent tries to use the Edit or Write tool on a file that the operating system has marked as read-only. This often happens in environments where build tools generate files or where version control systems lock certain configurations. The agent will show an error message in the terminal indicating that the operation was denied.

A read-only error prevents the agent from finishing its task. It might attempt to retry the operation several times, which consumes your tokens and increases the cost of the session. You can see this cost by using the /cost slash command. If the agent repeatedly fails to write to a file, it may get stuck in a loop. You should step in as soon as you see a permission error to save time and credits. Use the Escape key once to stop the agent from making further failed attempts.

Modifying file attributes with the Bash tool

Claude Code has the ability to run shell commands through the Bash tool. If you encounter a read-only file, you can instruct the agent to change the file permissions itself. For example, you can tell the agent to change the mode of a file to allow writing. The agent will then use the Bash tool to execute a command like chmod on your system. This is a fast way to resolve the issue without leaving the interactive session. The agent will report whether the command succeeded or if it requires higher privileges.

Sometimes the agent cannot change permissions because the file is owned by another user or the root system. If the Bash tool returns a permission error, you must handle the change in a separate terminal window on your machine. Once you have updated the file to be writable, you can return to the claude session and tell the agent to try the Edit tool again. The agent does not automatically know that you changed the file on the disk, so a quick prompt like the file is now writable will get it back on track.

Conflicts with IDE and system locks

External applications often lock files while they are in use. If you have an integrated development environment open, it might be holding a file handle that prevents Claude Code from making changes. This is common with heavy IDEs that perform background indexing or during an active debugging session. Even if the file is not strictly marked as read-only on the disk, the operating system treats it as such for any external write requests. The Write tool will fail with a message about the file being busy or locked by another process.

To fix this, you should close the file in your other editors or stop any running build processes that might be watching the directory. If you are using the /ide slash command to sync with your editor, ensure the editor is in a state that allows external edits. Once the lock is released, the agent can proceed with its work. If the agent continues to struggle with locks, you might need to use the /doctor command to check if there are any environmental issues affecting how the agent interacts with your filesystem.

Global and local settings for permissions

You can manage how Claude Code handles tool execution through the .claude/settings.json file in your project or the global ~/.claude/settings.json file for your user. These files allow you to define which tools are allowed to run and under what conditions. If you find that the agent is frequently blocked from writing to specific directories, you can check these settings to ensure the permissions section is correctly configured. You can also use the /permissions slash command during a session to see the current state of allowed tools.

Inside the settings.json file, you can specify if the agent should always ask for permission before using the Write or Edit tools. Setting these to be more permissive can speed up your workflow, but it also means the agent could attempt to overwrite read-only files more aggressively. If you use .claude/settings.local.json, you can set specific rules for your local machine that are not shared with the rest of your team through the git repository. This is useful for handling machine-specific file locks or path issues.

Using CLAUDE.md to guide the agent

The CLAUDE.md file is the best place to store project-specific instructions for the agent. If your project has specific files that should never be edited, or if certain files require a specific command to become writable, document it here. You can place a CLAUDE.md in the root of your repo or in any subdirectory. When the agent starts a session, it reads these instructions and follows them. Telling the agent to check if a file is writable before it attempts an edit can prevent many common errors.

In your CLAUDE.md, you can provide a list of directories that are managed by other tools and should be treated as read-only. For instance, you might tell the agent to never use the Write tool inside a folder containing generated documentation. This proactive approach keeps the agent focused on the code you actually want to change. It also reduces the number of times the agent gets confused by system-level errors that it cannot fix on its own. The agent is very good at following these written rules once they are established in the project root.

Handling errors across multiple project tiles

When you are working on a large system, you might have multiple Claude Code sessions running at once. This is where adhdTerminal becomes a valuable tool for your workflow. It allows you to run many sessions side by side as tiles on a wall. Each tile shows you the status of the session, including whether the agent is currently working or waiting for your input. If one session hits a read-only error, you will see it immediately on your wall without having to switch between different terminal tabs manually.

With adhdTerminal, you can give each tile a name and a color to keep track of different subdirectories. If you have a specific tile dedicated to a part of the project with many locked files, you can monitor its progress while you work in another tile. The iPhone app that comes with adhdTerminal even lets you see these updates from your phone. If an agent hits a permission error while you are away from your desk, you can use the mobile app to send a command or tell the agent how to proceed, ensuring your work continues without interruption.

Managing session context after failures

Every time the agent fails to write to a file, the error message and the failed attempt are added to the session context. Over time, these errors can fill up the context window, making the agent less efficient. You can use the /compact slash command to summarize the conversation so far. This cleans up the history by removing the detailed error logs while keeping the important parts of the discussion. It helps the agent stay focused on the task instead of getting distracted by past failures.

If a read-only error has completely derailed the conversation, you might want to use the /clear command. This starts the session over in the same folder, giving the agent a fresh start. Before you do this, make sure you have fixed the underlying file permission issue in your operating system. After clearing, you can use claude --continue to pick up the most recent session or just start a new prompt. Keeping the context window clean is essential for maintaining the quality of the agent's code suggestions.

Permission modes and the bypass option

Claude Code operates in different permission modes that change how it handles tool requests. You can cycle through these modes using Shift+Tab. The default mode asks for your permission for most write operations. The acceptEdits mode is more automated, and the bypassPermissions mode allows the agent to run tools without asking you at all. If you are dealing with a read-only file while in bypassPermissions mode, the agent will still fail, but it will fail faster because it does not stop to ask you for confirmation first.

Use bypassPermissions with caution, especially when your project contains sensitive files or system configurations. While it can make the agent feel much faster, it also gives it the power to attempt writes on any file it can see. If it hits a read-only file in this mode, it will report the error and move to the next logical step in its plan. You can check the current mode at any time by looking at the status bar in your terminal or by using the /status slash command to see the agent's current configuration and active limits.

Recovering from a stuck state

If the agent is stuck because of a persistent read-only error, you have a few ways to recover. Pressing the Escape key twice is a very powerful feature. It allows you to see a list of earlier messages in the session and jump back to a point before the error occurred. This effectively rewinds the conversation. Once you have jumped back, you can fix the file permissions in your shell and then give the agent a new instruction. This is often better than trying to explain the fix to the agent in the middle of an error loop.

You can also use the Ctrl+C command to quit the session entirely. Your progress is not lost, as you can use the claude --resume command to see a list of previous sessions and pick the one you were just working on. This is helpful if you need to perform significant system maintenance or restart your computer to clear a stubborn file lock. When you resume, the agent will have the context of the previous conversation, and you can tell it that the file issues have been resolved so it can continue with the project.

Questions people ask

Can Claude Code change file permissions by itself?

Yes, if you have allowed it to use the Bash tool. The agent can run commands like chmod to modify the file mode if your user account has the necessary rights on the operating system.

What should I do if a file is locked by another process?

You must identify the process holding the lock and stop it. This is often a running build tool, a debugger, or an IDE that is currently indexing the file. Once the process is stopped, the Write tool should work correctly.

How can I prevent the agent from trying to edit read-only files in the future?

You should add specific instructions to your CLAUDE.md file. List the directories or files that the agent should ignore or treat as read-only, and it will follow those instructions in every new session.

Read next

More on when it goes wrong·All posts