Claude Code «Error editing file»: pulsa Ctrl+O para ver la causa real (5 rechazos reproducidos)

En resumen: la línea Error editing file de Claude Code es solo una etiqueta. El motivo real está en el error completo de la herramienta, que se abre con Ctrl+O (vista transcript). El 10/11/2026 reprodujimos cinco rechazos habituales en Claude Code 2.1.312 con una API simulada local (sin login, sin enviar nada a Anthropic): archivo que no es UTF-8, regla Read deny, symlink, archivo sin leer antes y texto que ya no coincide. Los mensajes completos van abajo.

Paso 1: pulsa Ctrl+O para ver el error completo

La Error reference oficial (consultada el 10/11/2026; cita versiones hasta v2.1.318) explica, en la entrada sobre rutas que no se pueden resolver con seguridad, que cuando se bloquea una edición la vista de conversación muestra solo una línea corta Error editing file y que el mensaje completo está en la vista transcript (Ctrl+O). El mismo mensaje también llega a Claude como error de herramienta, así que a menudo reintenta por otro camino.

No pudimos capturar esa línea corta en la interfaz interactiva: probamos con claude -p (no interactivo), que imprime el resultado completo. Todas las citas salen de ahí.

Cinco causas de un vistazo

Obtén la línea completa con Ctrl+O y compara su inicio:

El mensaje empieza por	Qué significa	Qué hacer	Fuente
File is not valid UTF-8: it uses a legacy encoding such as Windows-1252, Shift-JIS or GBK, or it is binary.	El archivo no es UTF-8 (típico en archivos GBK antiguos); no se escribió nada	Convertir a UTF-8, o que Claude lo edite con un comando de shell en su codificación	Docs + reproducido en 2.1.312
File is covered by a Read deny rule in your permission settings and cannot be edited.	Una regla Read en permissions.deny coincide con la ruta	Acotar o quitar esa regla Read deny	Docs + reproducido en 2.1.312
Refusing to write /path/CLAUDE.md: it is a symbolic link. Write to the link's target path instead: /path/AGENTS.md.	El destino de escritura es un symlink	Editar el archivo real al que apunta	Docs + reproducido en 2.1.312
File has not been read yet. Read it first before writing to it.	Claude no ha leído este archivo en esta sesión	Que lo lea y luego edite	Reproducido en 2.1.312 (no está en la doc)
String to replace not found in file.	El texto antiguo no coincide con el archivo; quizá cambió	Que vuelva a leer el archivo y edite	Reproducido en 2.1.312 (no está en la doc)

Cómo lo reprodujimos

Montaje: Claude Code 2.1.312 (claude --version) con ANTHROPIC_BASE_URL apuntando a un pequeño servidor Python local. Hace de Messages API y solo emite una llamada Read y otra Edit guionizadas. Sin modelo real, sin login, sin peticiones a Anthropic. Ejecutamos claude -p con --permission-mode acceptEdits.

1. No UTF-8. Crea un archivo GBK:

printf '你好，世界\n版本=1\n' | iconv -f UTF-8 -t GBK > gbk.txt

El resultado de Read termina con una nota: [This file is not valid UTF-8: it uses a legacy encoding such as Windows-1252, Shift-JIS or GBK, or it is binary. ...]. Después Edit se rechaza. Texto completo (sin las etiquetas tool_use_error):

File is not valid UTF-8: it uses a legacy encoding such as Windows-1252, Shift-JIS or GBK, or it is binary. These tools write UTF-8 (or UTF-16LE behind its byte-order mark) and never convert a file's encoding on their own, so nothing was written. If the file is text, make the change with a shell command that reads and writes it in its own encoding (iconv, or PowerShell Get-Content/Set-Content -Encoding), or ask the user whether to convert it to UTF-8 first. To replace the whole file with new UTF-8 text anyway, delete it first, then Write it.

La doc redacta esta entrada algo distinto (It may use a legacy encoding ... Nothing was written.) de lo que imprimió 2.1.312; fíate de tu pantalla, la frase clave File is not valid UTF-8 es la misma. La doc añade que antes de v2.1.296 Edit guardaba los bytes ilegibles como U+FFFD, dañando el archivo sin avisar; actualiza las versiones antiguas.

2. Regla Read deny. Con {"permissions":{"deny":["Read(./secret.txt)"]}} en .claude/settings.json del proyecto, editar secret.txt devolvió:

File is covered by a Read deny rule in your permission settings and cannot be edited.

3. Symlink. Con CLAUDE.md creado con ln -s AGENTS.md CLAUDE.md, leer y editar CLAUDE.md devolvió:

Refusing to write /tmp/cct/proj/CLAUDE.md: it is a symbolic link. Write to the link's target path instead: /tmp/cct/proj/AGENTS.md.

4. Sin leer / texto no encontrado. Editar sin leer antes dio File has not been read yet. Read it first before writing to it. Tras leer, reemplazar un texto que no está dio String to replace not found in file. seguido del texto.

Dos casos que no reprodujimos (solo según la doc, no los demos por verificados):

• Rutas que no se pueden resolver con seguridad (aislamiento de worktree, symlink con .. en el destino): requiere una sesión en worktree, que no hicimos.
• permissions.blockWritesOutsideWorkingDirectories: con el ajuste en el proyecto en 2.1.312, una escritura fuera del directorio con bypassPermissions siguió funcionando. La documentación oficial dice que este ajuste requiere Claude Code v2.1.314 o posterior. No probamos una versión más nueva ni los ajustes de usuario, así que no decimos que falle, solo que no reprodujimos el bloqueo. Más en /permissions y blockWritesOutsideWorkingDirectories.

Soluciones por causa

1. No UTF-8

• Para seguir con Edit: copia de seguridad y conversión. De GBK a UTF-8:

cp gbk.txt gbk.txt.bak
iconv -f GBK -t UTF-8 gbk.txt.bak > gbk.txt

• Antes, comprueba si otras herramientas (scripts de build antiguos, programas heredados de Windows) esperan GBK. Si es así, no conviertas; deja que Claude use un comando de shell en la codificación original, como dice el mensaje.
• La doc añade que un archivo pensado como UTF-8 también se rechaza si contiene una sola secuencia de bytes inválida.

2. Regla Read deny

• Si Claude debe cambiar el archivo: acota o quita la regla Read deny en /permissions o en los ajustes.
• Si el archivo debe quedar intacto: deja la regla y añade una regla Edit deny para la misma ruta, que también bloquea NotebookEdit (consejo de la doc).

3. Symlink

Edita el archivo real que indica el mensaje. La doc da el mismo consejo para symlinks versionados cuyo destino contiene .., como docs/current -> ../README.md.

4. Sin leer, texto no encontrado

Ambos significan que la idea que Claude tiene del archivo difiere de lo que hay en disco. Que lo relea primero. Si se repite en el mismo archivo, revisa si un formateador, una herramienta de sincronización u otra sesión lo está editando a la vez.

5. Rutas bloqueadas, escrituras fuera del proyecto

Sigue la doc oficial: Claude suele reintentar con la ruta real que da el mensaje; para una escritura fuera del proyecto bloqueada usa /add-dir o quita el ajuste. No lo reprodujimos; mira la sección Tool errors de la Error reference.

FAQ

¿Por qué veo otro mensaje en modo -p o en scripts?

-p no tiene interfaz interactiva, así que el error completo sale en la salida. También vimos Claude requested permissions to write to /tmp/cct/outside.txt, but you haven't granted it yet.: una escritura sin aprobar fuera del proyecto falla así. No es un problema del archivo; piensa qué abres antes de añadir --permission-mode o --allowedTools.

¿Actualizar Claude Code lo arregla?

Solo en el comportamiento antiguo en que se dañaban en silencio los archivos no UTF-8 (se rechazan desde v2.1.296). Lo demás son problemas de configuración o del archivo que una actualización no cambia.

Más errores de Claude Code

Mira la guía de errores de Claude Code. Para el 400 por versión antigua: does not support this model; para bloqueos de Git: index.lock File exists.