Gemini CLI "ENAMETOOLONG: name too long" no write_file: como resolver

Você atualizou o Gemini CLI, pediu para o agente criar ou editar um arquivo de nome comprido, e o write_file (ou o replace) devolveu ENAMETOOLONG: name too long. O nome é válido: o shell grava o mesmo arquivo sem reclamar. Quem estoura o limite é o arquivo temporário que o Gemini CLI cria desde a versão 0.64.0, a estável atual.

Este guia mostra de onde vem o erro, como confirmar em um comando e três formas de destravar enquanto a correção oficial não sai. Tudo foi conferido no código-fonte e nos releases do repositório google-gemini/gemini-cli em 17/10/2026, e o limite foi reproduzido num sistema de arquivos ext4.

O que significa "ENAMETOOLONG" no write_file do Gemini CLI?

Significa que o sistema operacional recusou abrir um arquivo cujo nome passa de 255 bytes. O detalhe está no fim da mensagem: o caminho recusado termina em .tmp, não é o arquivo que você pediu.

Error writing to file '/projeto/docs/<nome-longo>.md': ENAMETOOLONG: name too long, open '/projeto/docs/<nome-longo>.md.8dcae82f-0430-47ee-adf0-bcd8979a3a72.tmp' (ENAMETOOLONG)

O arquivo não é criado. Se ele já existe, não dá para sobrescrever nem editar pelo agente. O caso está descrito na issue #29702, aberta em 10/10/2026.

Por que um nome válido dá erro na 0.64.0?

Porque a 0.64.0 passou a gravar de forma atômica: escreve num arquivo temporário ao lado do destino e depois renomeia. O nome do temporário é o nome do destino mais um UUID e .tmp, o que soma 41 bytes. Trecho de packages/core/src/services/fileSystemService.ts:

const tmpPath = `${realPath}.${randomUUID()}.tmp`;

Linux e macOS aceitam até 255 bytes por nome de arquivo (NAME_MAX). Então qualquer nome entre 215 e 255 bytes é legal para o sistema e ilegal para o temporário. No teste em ext4, um nome de 214 bytes gerou temporário de 255 e gravou; com 215 bytes, o temporário foi para 256 e falhou.

Versão	Como grava	Publicada
0.63.0	Escreve direto no destino, sem temporário	06/10/2026
0.64.0 (estável, tag latest)	Temporário + rename, falha acima de 214 bytes	13/10/2026
0.65.0-preview.0 e nightly 0.66.0 de 17/10	Mesmo código da 0.64.0	13/10 a 17/10/2026

Conta em bytes, não em caracteres

Letra sem acento ocupa 1 byte em UTF-8, letra acentuada ocupa 2 e ideograma chinês ou japonês ocupa 3. Um arquivo com 70 ideogramas e .md tem 213 bytes e passa. Com 71 ideogramas, são 216 bytes e o write_file falha. Nome gerado a partir de título de documento, slug longo ou nome com hash embutido chega lá rápido.

Atalho por symlink também não resolve: o Gemini CLI resolve o link para o caminho real antes de montar o nome do temporário, então quem conta é o nome do arquivo de destino.

Como confirmar que é esse o problema?

Veja a versão e conte o nome em bytes:

gemini --version
printf '%s' 'nome-do-arquivo.md' | wc -c

Se a versão é 0.64.0 ou mais nova e o número passa de 214, é este bug. Para achar de uma vez todos os arquivos do projeto que o write_file não consegue regravar:

find . -type f | LC_ALL=C awk -F/ 'length($NF) > 214'

O LC_ALL=C faz o awk contar bytes em vez de caracteres. E o limite do seu sistema de arquivos sai em getconf NAME_MAX . (255 em ext4, APFS e na maioria dos casos).

Como resolver o ENAMETOOLONG no Gemini CLI?

Encurte o nome para até 214 bytes. É o caminho mais simples e não depende de versão. Para o agente não voltar a gerar nome longo, deixe a regra no GEMINI.md do projeto:

Nomes de arquivo novos: no máximo 150 bytes. Use slug curto, sem título completo.

Precisa editar um arquivo que já existe com nome longo

Renomeie, edite e devolva o nome. O mv não usa temporário, então funciona com qualquer nome que o sistema aceite:

mv 'nome-longo-original.md' tmp-edit.md
# peça a edição no tmp-edit.md
mv tmp-edit.md 'nome-longo-original.md'

Outra saída é pedir que o agente grave pelo shell (run_shell_command) em vez do write_file. O shell escreve direto no destino, sem o sufixo de 41 bytes.

O nome não pode mudar: volte para a 0.63.0

1. Desligue a atualização automática no ~/.gemini/settings.json, senão o Gemini CLI volta sozinho para a 0.64.0:

   {
     "general": {
       "enableAutoUpdate": false
     }
   }

2. Instale a versão anterior:

   npm install -g @google/gemini-cli@0.63.0

Cuidado com a troca: a 0.63.0 tem o falso positivo de Untrusted Command Flags Detected no modo YOLO, que a 0.64.0 corrigiu. Explicamos esse aviso neste guia. Se você roda com --yolo, encurtar o nome costuma sair mais barato que voltar de versão.

Quando sai a correção oficial?

Ainda não saiu. O PR #29703, aberto em 10/10/2026, mantém o temporário na mesma pasta (para o rename continuar atômico) e corta o nome dele para caber em 255 bytes, com teste para nome ASCII de 254 bytes e nome longo em chinês. Em 17/10 ele seguia aberto, sem merge. Acompanhe a issue #29702 e, quando o fix entrar numa versão estável, religue o enableAutoUpdate.