# Claude Code Error writing file 오류 해결: Ctrl+O로 실제 메시지부터 확인

> Claude Code의 Error writing file은 요약 표시입니다. Ctrl+O 트랜스크립트 보기의 실제 메시지로 권한, 파일 변경 감지, 출력 잘림, 알려진 버그 중 원인을 가릅니다.

- URL: https://blog.laozhang.ai/ko/posts/claude-code-error-writing-file
- Published: 2026-10-16
- Updated: 2026-10-16
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: Claude Code
- Tags: Claude Code, Error writing file, Error editing file, 오류 해결, Write 도구

---
`Write(경로) ⎿ Error writing file`이 빨간 글씨로 뜨면 그 한 줄만으로는 원인을 알 수 없습니다. 대화 화면은 짧은 요약만 보여 주고, Claude가 실제로 받은 오류 문장은 **트랜스크립트 보기**(transcript view, `Ctrl+O`)에 있습니다. 그 문장이 `File has been modified since read`인지, `EACCES`인지, `content is missing`인지에 따라 처리가 완전히 갈립니다. 환경을 고칠 문제, Claude가 쓰는 방식을 바꿀 문제, 파일은 멀쩡한데 표시만 틀리는 버그로 나뉩니다.

아래 재현 결과는 2026년 10월 16일 macOS에서 Claude Code 2.1.295 데스크톱 앱과 Opus 5.5로 실행한 `Write` 7가지, `Edit` 2가지 경우입니다. Windows 환경, 출력 토큰 잘림, 버전별 버그는 직접 재현하지 않았고 공식 문서와 GitHub 이슈를 근거로 적었습니다. 같은 날 npm 최신 버전은 2.1.301입니다.

## `Error writing file` 실제 원인은 Ctrl+O 트랜스크립트 보기에 있습니다

공식 [Claude Code 오류 레퍼런스(errors)](https://code.claude.com/docs/en/errors#write-or-command-blocked-because-the-path-cannot-be-safely-resolved)는 파일 편집이 막혔을 때 대화 화면에는 짧은 `Error editing file` 한 줄만 나오고, 전체 메시지는 `Ctrl+O`로 여는 트랜스크립트 보기에 나온다고 설명합니다. [Claude Code 대화형 모드 문서의 단축키 표](https://code.claude.com/docs/en/interactive-mode)에서도 `Ctrl+O`는 트랜스크립트 보기를 켜고 끄는 키이며 "도구 사용과 실행 내용을 자세히" 보여 준다고 되어 있습니다. `Write`가 실패할 때의 `Error writing file`도 GitHub 이슈에 올라온 화면을 보면 같은 방식으로 요약됩니다.

확인 순서는 이렇습니다.

1. 터미널 CLI에서 `Ctrl+O`를 눌러 트랜스크립트 보기로 전환합니다. 단축키는 터미널과 플랫폼에 따라 다를 수 있습니다.
2. 실패한 `Write(...)` 또는 `Update(...)` 호출 아래에 붙은 오류 문장을 찾습니다. `Error:` 뒤에 이어지는 영어 문장이나 호출 아래에 그대로 적힌 오류 문장이 Claude가 받은 원문입니다.
3. 다시 `Ctrl+O`를 눌러 대화 화면으로 돌아갑니다.

데스크톱 앱에서는 도구 호출 결과에 이 원문이 그대로 표시됐습니다. VS Code·JetBrains 확장은 화면 구성이 달라 따로 확인하지 못했습니다. 원문을 찾기 어려우면 Claude에게 "방금 Write 도구가 받은 오류 메시지를 그대로 인용해 줘"라고 요청해도 됩니다. Claude는 전체 메시지를 도구 오류로 받기 때문입니다.

한 번 실패한 뒤 Claude가 스스로 다시 시도해 성공했다면 할 일은 없습니다. 오류 레퍼런스도 "대부분의 도구 오류는 Claude가 스스로 고친다"고 적고 있습니다. 문제는 같은 빨간 줄이 반복되거나, Claude가 `Write`를 포기하고 Bash·python으로 우회할 때입니다. 참고로 오류 레퍼런스에는 `Error writing file`이라는 문구 자체를 다루는 항목이 없습니다. 실제 메시지를 기준으로 찾아야 하는 이유입니다.

## 실제 메시지별 원인과 처리: 한눈에 보는 진단표

| 트랜스크립트에 보이는 메시지 | 원인 | 처리 | 분류 |
| --- | --- | --- | --- |
| `File has been modified since read, either by the user or by a linter.` | Claude가 읽은 뒤 에디터·포매터·hooks·다른 프로세스가 파일을 바꿈 | 파일을 다시 읽게 하고, 동시 편집을 멈춤 | 쓰는 방식 |
| `EACCES: permission denied, open '….tmp.….'` | 파일이 있는 폴더에 쓰기 권한이 없음 | 폴더 권한·소유자 수정 | 환경 |
| `EPERM: operation not permitted` (macOS 데스크탑·문서·다운로드·iCloud) | macOS 개인정보 보호가 터미널 앱을 막음 | 시스템 설정에서 폴더 접근 허용 | 환경 |
| `… is a directory, not a file.` | 경로가 폴더를 가리킴 | 파일 이름까지 넣은 경로로 다시 쓰기 | 경로 |
| `InputValidationError: Write failed … content is missing` | 도구 호출 인자가 비었거나 중간에 잘림 | 뼈대를 먼저 쓰고 작게 나눠 채우기 | 쓰는 방식 |
| `API Error: Claude's response exceeded the … output token maximum` | 한 번의 응답이 출력 한도를 넘음 | `continue`, 한 번에 파일 하나·섹션 하나 | 쓰는 방식 |
| `File is not valid UTF-8.` | EUC-KR·CP949 같은 레거시 인코딩 파일 | UTF-8로 변환하거나 인코딩을 유지하는 셸 명령 사용 | 환경 |
| `Refusing to write …: it is a symbolic link.` / `This write was blocked because the path …` | 심볼릭 링크, worktree 격리, 네트워크 경로 | 링크가 아닌 실제 경로로 쓰기 | 경로 |
| `ENOSPC` / `EDQUOT` | Claude Code 임시 디렉터리의 디스크·쿼터가 가득 참 | 디스크 공간 확보 | 환경 |
| `Command failed: cygpath -u '…'` | Windows Git Bash에서 경로 변환 실패 | 알려진 버그로 다룸 | 버그 |
| 상세 메시지가 없거나, 파일이 이미 정상으로 써져 있음 | 상대 경로·plan 모드 오탐 등 알려진 버그 | 디스크 확인 후 무시, 업데이트 | 버그 |

메시지 원문은 [Claude Code 오류 레퍼런스](https://code.claude.com/docs/en/errors), [Claude Code 도구 레퍼런스(tools-reference)](https://code.claude.com/docs/en/tools-reference), 로컬 재현 결과, 아래 각 절에 단 GitHub 이슈에서 가져왔습니다. 이 중 `File has been modified since read`, `EACCES`, `is a directory` 세 메시지는 2.1.295에서 직접 재현했습니다.

"폴더가 없어서 실패한다"는 추측은 맞지 않습니다. 존재하지 않는 `newparent/sub/file.txt`에 `Write`를 시켰더니 상위 폴더를 자동으로 만들고 `File created successfully`로 끝났습니다.

## `File has been modified since read`: 에디터·포매터 충돌

Claude가 파일을 읽은 뒤 디스크의 파일이 바뀌면 `Write`는 덮어쓰기를 거부합니다. 파일을 읽고, 셸에서 `echo`로 내용을 바꾼 다음 `Write`를 시키자 아래 문장이 그대로 나왔습니다.

```text
File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.
```

실제로 이 상황을 만드는 것은 대개 사람이 아니라 도구입니다.

- **에디터·IDE**: macOS에서 IDE가 파일을 열거나 미리 보기만 해도 수정 시각이 바뀌어 같은 오류가 났다는 보고가 있습니다([GitHub 이슈 #10498: IDE가 파일을 열 때의 Write 오탐](https://github.com/anthropics/claude-code/issues/10498)). 내용은 그대로여도 저장 동작이 일어나면 걸립니다.
- **포매터와 hooks**: 편집 직후 Prettier 같은 포매터를 돌리는 `PostToolUse` 훅은 Claude가 기억하는 내용과 디스크 내용을 어긋나게 만듭니다. 훅 구성은 [Claude Code Hooks·Skills·슬래시 명령어 차이와 사용 예제](https://blog.laozhang.ai/ko/posts/claude-code-hooks-slash-commands-skills)에서 확인할 수 있습니다.
- **다른 프로그램의 잠금**: Windows에서는 다른 프로그램이 쥐고 있는 파일이 `File has been unexpectedly modified`라는 엉뚱한 메시지로 나타난다는 보고가 있고([GitHub 이슈 #10245](https://github.com/anthropics/claude-code/issues/10245)), WSL·Unity 에디터 환경에서 같은 문구가 반복되다 재시작하면 잠시 풀린다는 보고도 있습니다([GitHub 이슈 #11463](https://github.com/anthropics/claude-code/issues/11463)).

처리는 두 단계입니다. 먼저 Claude가 쓰는 동안 같은 파일을 에디터에서 저장하지 않고, 저장 시 자동 포맷처럼 파일을 다시 쓰는 기능이 겹치는지 확인합니다. 그다음 "파일을 다시 읽고 나서 써 줘"라고 지시합니다. 메시지 자체가 다시 읽으라고 말하고 있으므로 보통은 Claude가 알아서 처리합니다.

부분 수정이라면 `Write`보다 `Edit`이 덜 걸립니다. v2.1.208부터 `Edit`은 읽은 뒤 바뀐 파일이라도 `old_string`이 현재 내용과 정확히 한 번 일치하면 그대로 적용합니다([도구 레퍼런스의 Edit 도구 동작](https://code.claude.com/docs/en/tools-reference#edit-tool-behavior)). `Write`는 파일 전체를 덮어쓰기 때문에 이런 완화가 없습니다.

## `EACCES: permission denied`와 `.tmp.` 경로: 폴더 쓰기 권한 문제

권한 오류에서 눈여겨볼 것은 메시지에 찍힌 파일 이름입니다. 권한이 `555`(쓰기 불가)인 폴더에 `new.txt`를 쓰게 하자 이런 메시지가 나왔습니다.

```text
EACCES: permission denied, open '/…/rodir/new.txt.tmp.35734.7a96eba60d51'
```

`new.txt`가 아니라 `new.txt.tmp.35734.7a96eba60d51`이라는 임시 파일을 열다 실패했습니다. 이름 형식(파일명.tmp.프로세스번호.16진수)으로 보면 `Write`는 같은 폴더에 임시 파일을 먼저 쓰고 그 이름을 바꾸는 방식으로 저장합니다. 그래서 중요한 것은 파일 권한이 아니라 **폴더의 쓰기 권한**입니다.

직관과 다른 결과도 하나 있습니다. 쓰기 가능한 폴더 안에서 파일을 `chmod 444`(읽기 전용)로 바꿔 두었는데도 `Write`가 내용을 덮어썼고, 권한 표시는 `-r--r--r--` 그대로 남았습니다. 임시 파일을 만든 뒤 이름을 바꾸는 방식이라 파일 자체의 읽기 전용 비트는 막지 못합니다.

![Write 도구가 임시 파일을 쓴 뒤 이름을 바꾸는 과정과, 폴더 555는 EACCES로 막히고 파일 444는 덮어쓰기를 막지 못하는 차이](https://blog.laozhang.ai/posts/ko/claude-code-error-writing-file/img/write-temp-file-rename.webp)

해결은 이렇게 합니다.

```bash
ls -ld ./src/generated          # 폴더 권한과 소유자 확인
sudo chown -R "$(whoami)" ./src/generated   # 다른 사용자 소유라면 소유자 변경
chmod u+w ./src/generated       # 본인 소유인데 쓰기 권한만 없다면
```

반대로 특정 파일을 Claude가 건드리지 못하게 하고 싶다면 `chmod 444` 대신 권한 규칙을 씁니다. 도구 레퍼런스에 따르면 `Edit(...)` 규칙은 `Edit`, `Write`, `NotebookEdit`에 모두 적용됩니다.

```json
{
  "permissions": {
    "deny": ["Edit(./config/production.env)"]
  }
}
```

`Read(...)` deny 규칙도 같은 경로의 `Edit`과 `Write`를 막습니다(쓰기는 v2.1.228부터). 승인 생략 모드에서도 deny 규칙이 어떻게 남는지는 [Claude Code --dangerously-skip-permissions 사용법과 승인 생략의 범위](https://blog.laozhang.ai/ko/posts/claude-code-dangerously-skip-permissions)에 정리되어 있습니다.

## macOS `EPERM`: 데스크탑·문서·다운로드 폴더 접근 차단

macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads`, iCloud Drive 안의 프로젝트에서 `EPERM: operation not permitted`가 나오면 파일 권한이 아니라 macOS가 터미널 앱의 폴더 접근을 막고 있을 가능성이 큽니다. 이때는 같은 폴더에서 `ls`를 실행해도 `Operation not permitted`가 나오고, `sudo`를 붙여도 마찬가지입니다.

1. 터미널 앱을 `Cmd+Q`로 완전히 종료한 뒤 다시 열고 같은 폴더에서 `claude`를 실행합니다.
2. 그래도 `ls`가 실패하면 **시스템 설정 > 개인정보 보호 및 보안 > 파일 및 폴더**(Privacy & Security > Files and Folders)에서 해당 터미널 앱의 폴더 접근을 켭니다.
3. 터미널을 다시 엽니다.

공식 오류 레퍼런스는 이 내용을 작업 디렉터리를 읽지 못하는 경우로 설명합니다. 같은 운영체제 차단이 쓰기에도 적용되므로 `Write`의 `EPERM`에도 같은 순서가 통합니다. 프로젝트를 이 네 위치가 아닌 홈 아래 폴더(예: `~/dev`)로 옮겨도 이 차단을 피할 수 있습니다.

## `content is missing`과 출력 한도 초과: 큰 파일은 나눠서 쓰기

다음 메시지는 디스크나 권한과 관계가 없습니다. Claude가 보낸 도구 호출 자체에 파일 경로나 내용이 빠져 있다는 뜻입니다.

```text
InputValidationError: Write failed due to the following issue:
The required parameter `content` is missing
```

[GitHub 이슈 #895](https://github.com/anthropics/claude-code/issues/895)는 2026년 10월 16일 기준으로 아직 열려 있고, 큰 파일, 긴 세션, 서브에이전트에서 이 오류가 같은 문구로 계속 반복되는 사례가 모여 있습니다. 같은 지시를 다시 내려도 Claude가 또 빈 인자로 호출하는 일이 흔하므로 재시도만으로는 잘 풀리지 않습니다.

여러 사용자가 효과를 확인한 방법은 같습니다.

1. 먼저 함수 이름과 주석만 담은 뼈대 파일을 씁니다.
2. 그 뒤 100~200줄 정도씩 나눠 채우게 합니다.
3. 반복되는 프로젝트라면 `CLAUDE.md`에 "큰 파일은 여러 번에 나눠 쓴다"는 규칙을 넣습니다.

출력 한도에 걸린 경우도 비슷하게 다룹니다. 응답이 한도를 넘으면 `API Error: Claude's response exceeded the 32000 output token maximum…` 같은 메시지가 나오고, 큰 테스트 스크립트를 만들다 이 메시지 직후 `Error writing file`이 이어진 사례가 있습니다([GitHub 이슈 #7927](https://github.com/anthropics/claude-code/issues/7927)). [오류 레퍼런스의 출력 토큰 한도 항목](https://code.claude.com/docs/en/errors#response-exceeded-the-output-token-maximum)은 `continue`로 이어 받거나 "한 번에 파일 하나 또는 섹션 하나"씩 요청하라고 안내합니다. 스트리밍이 실패해 비스트리밍으로 다시 보낸 요청은 64,000 토큰으로 제한되며 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`로도 늘릴 수 없습니다. v2.1.299 이전에는 이렇게 잘린 응답이 아무 메시지 없이 끝났기 때문에, 그보다 오래된 버전이라면 업데이트하는 편이 원인을 보기 쉽습니다.

게이트웨이나 서드파티 모델을 거칠 때는 특히 자주 나타납니다. 이슈 #895의 한 댓글은 LiteLLM 같은 OpenAI 호환 프록시에서 스트리밍이 실패하면 출력 한도가 낮은 비스트리밍 요청으로 바뀌면서 도구 호출 JSON이 중간에 잘린다고 분석했습니다. Anthropic이 확인한 설명은 아닙니다. GLM 4.5에서 4.7로 바꾼 뒤 모든 도구 호출이 빈 인자로 도착했다는 댓글도 있습니다. 이런 환경에서 같은 오류가 이어진다면 프롬프트보다 연결 경로를 먼저 의심합니다. 설정 확인 순서는 [Claude Code API 설정: 키, settings.json, 모델, 게이트웨이 확인 순서](https://blog.laozhang.ai/ko/posts/claude-code-api-configuration), 서드파티 모델 경로는 [Claude Code에서 OpenRouter와 DeepSeek 쓰기](https://blog.laozhang.ai/ko/posts/claude-code-openrouter-deepseek)를 참고하세요.

## EUC-KR·CP949 파일과 `File is not valid UTF-8`

오래된 Windows 프로젝트의 소스, CSV, 설정 파일은 EUC-KR이나 CP949로 저장된 경우가 많습니다. 이런 파일에 `Edit`을 시키면 아래 메시지와 함께 거부되고 파일은 그대로 남습니다.

```text
File is not valid UTF-8. It may use a legacy encoding such as Windows-1252, Shift-JIS or GBK, or be binary
```

메시지에 한국어 인코딩 이름은 없지만 EUC-KR·CP949 한글 파일도 UTF-8이 아니므로 같은 경우에 해당합니다. 주의할 쪽은 `Write`입니다. [도구 레퍼런스의 비 UTF-8 파일 항목](https://code.claude.com/docs/en/tools-reference#non-utf-8-files)에 따르면 `Write`는 이런 파일도 덮어쓸 수 있고, 저장은 UTF-8로 합니다. 즉 `Write`가 성공하면 원래 인코딩이 사라집니다. 레거시 인코딩을 읽는 빌드 도구나 프로그램이 있다면 여기서 깨집니다.

이 거부 동작은 v2.1.296부터입니다. [오류 레퍼런스의 File is not valid UTF-8 항목](https://code.claude.com/docs/en/errors#file-is-not-valid-utf-8)에 따르면 그 이전 버전의 `Edit`과 `NotebookEdit`은 수정을 그대로 적용하고, 읽지 못한 바이트를 모두 `U+FFFD`로 바꿔 저장했습니다. EUC-KR·CP949 파일의 한글이 오류 메시지 없이 깨질 수 있으므로, `claude --version`이 2.1.296보다 낮다면 먼저 업데이트합니다.

인코딩 확인과 변환은 macOS에서 다음 명령으로 확인했습니다.

```bash
iconv -f UTF-8 -t UTF-8 legacy.txt > /dev/null   # "Illegal byte sequence"가 나오면 UTF-8이 아님
iconv -f CP949 -t UTF-8 legacy.txt > legacy.utf8.txt   # UTF-8로 변환
```

macOS의 `file -I`는 CP949 파일을 `iso-8859-1`로 잘못 표시했으므로 판단 근거로 쓰지 않는 편이 낫습니다. UTF-8로 바꿔도 되는 프로젝트라면 변환 후 Claude에게 맡기고, 인코딩을 유지해야 한다면 그 사실을 Claude에게 알려 셸 명령으로 수정하게 합니다.

## 읽지 않은 파일에 대한 Write 실패: 모델과 버전에 따라 다릅니다

"쓰기 전에 반드시 읽어야 한다"는 규칙은 이제 모든 경우에 적용되지 않습니다. [도구 레퍼런스의 Write 도구 동작](https://code.claude.com/docs/en/tools-reference#write-tool-behavior) 기준으로 정리하면 다음과 같습니다.

| 조건 | 기존 파일 덮어쓰기 전 Read |
| --- | --- |
| Claude Opus 4.6, Claude Haiku 4.5 및 그 이전 모델 | 항상 필요. 읽지 않은 파일에 쓰면 실패 |
| 그보다 새 모델, v2.1.228 이상 | 읽을 때 권한 확인이 필요 없고 Read 도구가 있으면 생략 가능 |
| Jupyter 노트북, `PARTIAL view` 안내와 함께 일부만 읽은 파일 | 모든 모델에서 전체 읽기 필요 |
| 새로 만드는 파일 | 해당 없음 |
| v2.1.228 미만 | 모든 모델에서 필요 |

Opus 5.5로 한 번도 읽지 않은 기존 파일에 `Write`를 시키자 그대로 성공했습니다. 162KB 파일을 앞 3줄만 읽은 뒤 쓰는 경우도 성공했습니다. 줄 수를 지정해 읽은 것은 `PARTIAL view` 읽기가 아니기 때문으로 보이며, 부분 읽기 규칙 자체는 재현하지 못했습니다. 오래된 모델에서 나는 "읽지 않음" 오류의 정확한 문구도 확보하지 못했습니다. 트랜스크립트에 읽기를 요구하는 메시지가 보이면 Claude에게 파일을 먼저 읽게 하면 됩니다. `cat`, `head`, `sed -n`, `grep`처럼 파일 하나를 보는 Bash 명령도 읽기로 인정됩니다.

## 폴더 경로·심볼릭 링크·worktree 경로가 막힐 때

경로 문제는 각자 고유한 메시지를 내므로 트랜스크립트만 보면 바로 구분됩니다.

- **경로가 폴더**: `… is a directory, not a file. To create a file inside it, include the file name in file_path.` 직접 재현한 메시지입니다. 파일 이름까지 넣은 경로로 다시 쓰게 합니다.
- **심볼릭 링크**: `Refusing to write …: it is a symbolic link. Write to the link's target path instead`. 링크가 가리키는 실제 파일 경로로 쓰게 합니다.
- **worktree로 격리된 세션**: `This write was blocked because the path is spelled in a form that cannot be safely resolved…`. 보통 Claude가 메시지가 알려 주는 직접 경로로 다시 시도합니다. 같은 파일에서 반복되면 커밋된 심볼릭 링크의 대상에 `..`가 들어 있는 경우이니 실제 경로로 편집하라고 지시합니다.
- **네트워크 경로**: UNC 공유(`\\server\share`)나 `/net` 경로는 로컬 체크아웃 세션에서 차단되며, worktree로 격리해도 풀리지 않습니다. 로컬 경로를 써야 합니다.
- **임시 디렉터리 용량**: `ENOSPC`나 `EDQUOT`은 Claude Code 임시 디렉터리가 있는 파일 시스템의 공간이나 쿼터가 찬 경우입니다.

## 파일은 써졌는데 `Error writing file`이 뜨는 알려진 버그

트랜스크립트에 쓸 만한 원인이 없고 파일은 디스크에 제대로 있다면 표시 쪽 버그일 수 있습니다. GitHub에 보고된 경우는 다음과 같습니다. 모두 수정 내역 없이 오래된 이슈로 자동 종료되어 지금 버전에서 고쳐졌는지는 알 수 없습니다.

| 증상 | 보고된 버전 | 실제 결과 | 출처 |
| --- | --- | --- | --- |
| 상대 경로로 쓴 파일마다 빨간 `Error writing file` | v2.1.63, macOS | 파일은 정상 생성 | [이슈 #29841](https://github.com/anthropics/claude-code/issues/29841) |
| plan 모드에서 계획 파일 첫 쓰기가 항상 실패 | v2.1.37~2.1.50 (WSL2, macOS, Ubuntu, Manjaro) | 자동 재시도에서 성공 | [이슈 #24151](https://github.com/anthropics/claude-code/issues/24151) |

이런 경우에는 파일 내용을 확인한 뒤 무시하면 됩니다. 반복되면 최신 버전으로 업데이트하고(npm 설치라면 `npm install -g @anthropic-ai/claude-code@latest`), `claude --version`으로 버전을 확인한 다음 다시 시도합니다.

### Windows에서 `Error writing file`: Git Bash 특수 문자와 cygpath

Windows 환경은 직접 재현하지 못했지만 보고 내용은 구체적입니다.

- Windows 10의 Git Bash에서 파일 내용에 작은따옴표, 백슬래시, XML·HTML 닫는 태그가 들어가면 `Write`·`Edit`이 `Error writing file` / `Error editing file`로 반복 실패하고, Claude가 `python -c`나 heredoc으로 우회했다는 보고가 있습니다([이슈 #63838](https://github.com/anthropics/claude-code/issues/63838)).
- Windows MINGW64에서 모든 `Write`가 `Command failed: cygpath -u '…'`로 실패한 사례는 사용자 폴더가 `HIPOLI~1` 같은 8.3 짧은 이름으로 바뀐 임시 경로와 함께 나타났습니다([이슈 #25971](https://github.com/anthropics/claude-code/issues/25971)).

둘 다 사용자 설정으로 고칠 방법이 공식적으로 나온 것은 아닙니다. 최신 버전으로 올리고, 같은 실패가 계속되면 트랜스크립트의 원문을 붙여 이슈로 보고하는 것이 현실적인 대응입니다.

## `Error editing file`과 `String to replace not found`

`Update(경로) ⎿ Error editing file`은 `Edit` 도구의 같은 요약 표시입니다. 원인을 찾는 방법도 같아서 `Ctrl+O`로 원문을 봅니다. `Edit`에만 있는 실패 조건은 두 가지입니다.

- **문자열 불일치**: `old_string`이 파일에 정확히 그대로 있어야 합니다. 공백이나 들여쓰기 한 글자만 달라도 실패하며, 2.1.295에서 재현한 실제 메시지는 `String to replace not found in file.`입니다. 포매터가 들여쓰기를 바꿨거나 Claude가 기억하는 내용이 오래된 경우라면 파일을 다시 읽게 하면 풀립니다.
- **중복 일치**: `old_string`이 파일에 두 번 이상 나오면 `Found 2 matches of the string to replace, but replace_all is false.`로 거부됩니다(2.1.295에서 재현). 앞뒤 문맥을 더 넣거나, 전부 바꾸는 것이 맞다면 `replace_all`을 쓰게 합니다.

`Edit`은 비 UTF-8 파일을 거부하고, `Read(...)` deny 규칙이 걸린 경로도 거부합니다. 이 두 경우는 몇 번을 다시 시도해도 결과가 같습니다.

## 같은 오류가 반복될 때 재시도를 멈추는 기준과 결과 확인

다음 중 하나에 해당하면 `Esc`로 멈추고 방식을 바꾸는 편이 토큰과 시간을 덜 씁니다.

- **이미 파일이 써져 있음**: 상대 경로·plan 모드 오탐처럼 표시만 틀린 경우입니다. 다시 쓰게 하면 같은 내용을 반복할 뿐입니다.
- **`content is missing`이 두 번 이상 연속**: 같은 크기로 다시 시도해도 같은 결과가 나오기 쉽습니다. 뼈대부터 나눠 쓰게 합니다.
- **게이트웨이·서드파티 모델에서만 발생**: 인자가 잘리는 쪽이 연결 경로라면 프롬프트를 바꿔도 해결되지 않습니다. 연결 설정을 먼저 확인합니다.
- **환경 원인**: `EACCES`, `EPERM`, 인코딩, 경로 차단은 사람이 환경을 바꾸기 전에는 결과가 같습니다.

![같은 쓰기 오류가 반복될 때 재시도를 멈출 네 가지 신호와 디스크에서 결과를 확인하는 명령 목록](https://blog.laozhang.ai/posts/ko/claude-code-error-writing-file/img/stop-retry-checklist.webp)

Claude가 Bash의 heredoc이나 python으로 우회해 파일을 쓰는 것 자체가 늘 나쁜 것은 아닙니다. 다만 우회 쓰기는 `Write`의 "읽은 뒤 바뀌었는지" 확인을 거치지 않는 경로이므로, 원인이 `File has been modified since read`였다면 에디터에서 바꾼 내용을 덮어쓸 수 있습니다. 인코딩 문제였다면 우회 명령이 어떤 인코딩으로 저장했는지도 봐야 합니다.

마지막으로 화면 표시가 아니라 디스크에서 결과를 확인합니다.

```bash
git status --short                 # 바뀐 파일 목록
git diff -- src/app.py             # 실제 변경 내용
wc -l src/app.py && tail -n 5 src/app.py   # 중간에 잘리지 않았는지 끝부분 확인
ls -l src/app.py                   # 크기와 수정 시각
```

큰 파일을 나눠 썼다면 끝부분이 함수 중간에서 끊기지 않았는지, 빌드나 테스트가 통과하는지까지 보면 확실합니다. 파일 쓰기 문제가 아니라 Claude Code 프로세스 자체가 종료된다면 [Claude Code process exited with code 1 해결](https://blog.laozhang.ai/ko/posts/error-claude-code-process-exited-with-code-1)에서 다른 갈래로 확인합니다.

## 2.1.295 재현 환경: 실행한 것과 실행하지 않은 것

2026년 10월 16일, macOS(Darwin 25.1.0)의 Claude Code 2.1.295 데스크톱 앱, Opus 5.5 모델, 승인 생략 권한 모드로 `Write` 7가지, `Edit` 2가지 경우를 실행했습니다. 기록한 것은 Claude가 받은 도구 결과 원문입니다.

| 경우 | 결과 |
| --- | --- |
| 권한 `555` 폴더에 새 파일 쓰기 | `EACCES: permission denied`, 임시 파일 경로 표시 |
| 쓰기 가능한 폴더의 `chmod 444` 파일 덮어쓰기 | 성공, 권한은 `-r--r--r--` 유지 |
| 폴더 경로에 쓰기 | `… is a directory, not a file` |
| 읽은 뒤 셸로 내용 변경, 다시 쓰기 | `File has been modified since read…` |
| 읽지 않은 기존 파일 덮어쓰기 | 성공 |
| 162KB 파일을 3줄만 읽고 덮어쓰기 | 성공 |
| 존재하지 않는 상위 폴더 아래에 쓰기 | 성공, 폴더 자동 생성 |
| `Edit`: 파일에 없는 `old_string`으로 수정 | `String to replace not found in file.` |
| `Edit`: 두 번 나오는 `old_string`, `replace_all` 없이 수정 | `Found 2 matches of the string to replace, but replace_all is false.` |

실행하지 않은 것은 Windows 환경, 출력 토큰 잘림, 상대 경로·plan 모드 버그, IDE 미리 보기로 인한 오탐, worktree·심볼릭 링크·네트워크 경로 차단입니다. 이 부분은 위에 단 공식 문서와 GitHub 이슈에 근거합니다. 같은 날 최신 버전은 2.1.301이므로, 이후 버전에서는 메시지 문구나 동작이 달라질 수 있습니다.

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-10-16.

- [Claude Code 오류 레퍼런스(errors)](https://code.claude.com/docs/en/errors) (code.claude.com)
- [Claude Code 대화형 모드 문서의 단축키 표](https://code.claude.com/docs/en/interactive-mode) (code.claude.com)
- [Claude Code 도구 레퍼런스(tools-reference)](https://code.claude.com/docs/en/tools-reference) (code.claude.com)
- [GitHub 이슈 #10498: IDE가 파일을 열 때의 Write 오탐](https://github.com/anthropics/claude-code/issues/10498) (github.com)
- [GitHub 이슈 #10245](https://github.com/anthropics/claude-code/issues/10245) (github.com)
- [GitHub 이슈 #11463](https://github.com/anthropics/claude-code/issues/11463) (github.com)
- [GitHub 이슈 #895](https://github.com/anthropics/claude-code/issues/895) (github.com)
- [GitHub 이슈 #7927](https://github.com/anthropics/claude-code/issues/7927) (github.com)
- [이슈 #29841](https://github.com/anthropics/claude-code/issues/29841) (github.com)
- [이슈 #24151](https://github.com/anthropics/claude-code/issues/24151) (github.com)
- [이슈 #63838](https://github.com/anthropics/claude-code/issues/63838) (github.com)
- [이슈 #25971](https://github.com/anthropics/claude-code/issues/25971) (github.com)