O `InvalidCharError` das bibliotecas de sanitização de nomes de arquivo do Python é um erro preciso - ele dispara quando uma string de nome de arquivo contém um caractere proibido pelo sistema operacional de destino. Mas a causa quase sempre é a mesma: um nome de arquivo chegou de entrada do usuário, upload de arquivo ou API externa sem ser validado antes. Este guia explica exatamente quais caracteres disparam o erro em cada SO, como corrigi-lo e como incorporar a sanitização ao seu código para que ele nunca chegue à produção.
O que é FilenameSanitizer?
`FilenameSanitizer` refere-se a bibliotecas Python - mais comumente `python-filenamesanitizer` e pacotes semelhantes - que validam e limpam strings de nomes de arquivo antes de serem usadas em operações do sistema de arquivos. Essas bibliotecas verificam o nome proposto contra as regras do sistema operacional de destino e retornam uma versão sanitizada ou lançam uma exceção quando um caractere não pode ser substituído com segurança.
Por que a sanitização de nomes de arquivo é necessária
Nomes de arquivo vindos de fontes externas - uploads de usuários, respostas de API, dados raspados, registros de banco de dados - frequentemente contêm caracteres perfeitamente válidos no contexto de origem, mas ilegais no sistema de arquivos de destino. Um nome como `report: Q1/2026.pdf` é um rótulo humano razoável, mas contém `:` e `/` - ambos ilegais no Windows. Sem sanitização, a chamada `open()` lança um `OSError` ou o arquivo é silenciosamente truncado no caractere ilegal.
O que significa InvalidCharError
InvalidCharError é a exceção específica lançada quando um nome de arquivo contém um caractere que a biblioteca não consegue substituir ou remover automaticamente - ou quando a biblioteca está configurada para lançar em vez de autocorrigir. A mensagem da exceção inclui o nome original e o caractere ofensor, o que lhe dá tudo de que precisa para corrigir. Se você vê esse erro sem um traceback claro, cole o stack trace completo no Explicador de Tracebacks Python para uma análise em linguagem clara da causa raiz.
Note
O que dispara o InvalidCharError?
O erro dispara quando a string do nome de arquivo contém um ou mais caracteres que o conjunto de regras do sanitizador marca como ilegais. Os gatilhos mais comuns se enquadram em quatro categorias, cada uma com um caminho de correção diferente.
- Separadores de caminho do Windows - `:` (dois-pontos), `\\` (barra invertida), `/` (barra inclinada); aparecem com frequência em carimbos de data/hora e caminhos de URL usados como nomes de arquivo
- Caracteres reservados do shell - `|`, `<`, `>`, `?`, `*`, `"` - comuns em nomes gerados a partir de consultas de busca, títulos ou nomes de documentos
- Bytes nulos e caracteres de controle - pontos de código Unicode U+0000 a U+001F; às vezes injetados por entrada maliciosa ou corrupção de codificação
- Nomes de dispositivos reservados do Windows - CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9 - ilegais como nomes de arquivo independentemente da extensão no Windows
O problema do carimbo de data/hora
A fonte mais comum de `InvalidCharError` em aplicações reais é um nome de arquivo construído a partir de um carimbo de data/hora. Um datetime ISO 8601 como `2026-06-11T14:30:00` contém dois-pontos - ilegais no Windows. Qualquer código que gere nomes como `backup_2026-06-11T14:30:00.zip` falhará no Windows, mas terá êxito silenciosamente no Linux, criando um bug multiplataforma sutil. Substitua os dois-pontos nos carimbos de data/hora por hífens ou pontos: `2026-06-11T14-30-00`.
O problema da entrada do usuário
Quando usuários nomeiam arquivos em uma interface web ou enviam arquivos de seus dispositivos, os nomes chegam sem qualquer garantia de validade. Um PDF chamado `Invoice: Client/Project Q4.pdf` é um nome totalmente natural, escrito por humano, que contém três caracteres ilegais no Windows. Trate sempre qualquer nome de arquivo que não se originou no seu próprio código como entrada não confiável que exige sanitização antes do uso.
Warning
Caracteres ilegais por sistema operacional
Os três principais sistemas operacionais têm regras muito diferentes sobre quais caracteres são permitidos em nomes de arquivo. Entender as diferenças é essencial para escrever código portátil de manipulação de arquivos.
| Caractere | Windows | macOS | Linux |
|---|---|---|---|
| / (barra inclinada) | ✗ Ilegal | ✗ Ilegal | ✗ Ilegal (sep. de caminho) |
| \\ (barra invertida) | ✗ Ilegal | ✓ Permitido | ✓ Permitido |
| : (dois-pontos) | ✗ Ilegal | ✗ Questão legada | ✓ Permitido |
| * ? " < > | (conjunto) | ✗ Ilegal | ✓ Permitido | ✓ Permitido |
| Byte nulo (\0) | ✗ Ilegal | ✗ Ilegal | ✗ Ilegal |
| Caracteres de controle (0-31) | ✗ Ilegal | ✗ Ilegal | ✗ Ilegal |
| Ponto inicial (.) | ✓ Permitido | Arquivo oculto | Arquivo oculto |
| Ponto ou espaço final | ✗ Ilegal | ✓ Permitido | ✓ Permitido |
| Nomes reservados (CON etc.) | ✗ Ilegal | ✓ Permitido | ✓ Permitido |
Para código multiplataforma que precise funcionar nos três sistemas, a regra segura é tratar as regras do Windows como o mínimo - qualquer caractere ilegal no Windows deve ser sanitizado independentemente do SO real em execução. Isso lhe dá nomes de arquivo portáteis que funcionam em todo lugar. O Sanitizador de Nomes de Arquivo para Uploads Multiplataforma valida contra os três conjuntos de regras de SO simultaneamente para que você possa verificar qualquer nome em uma única passagem.
Como corrigir o erro
Corrigir um `InvalidCharError` sempre envolve o mesmo fluxo de trabalho: encontrar a origem do nome, aplicar a sanitização antes da chamada ao sistema de arquivos e verificar o resultado. Siga estes passos em ordem.
Leia o traceback completo para identificar o caractere ofensor
A mensagem de `InvalidCharError` inclui tanto a string original do nome quanto o caractere específico rejeitado. Copie o traceback completo e anote o caractere. Se for um caractere de controle ou byte nulo, ele pode não estar visível na saída do erro - use `repr()` na string do nome no seu código para ver a representação escapada e identificar os caracteres ocultos.
Localize de onde o nome se origina no seu código
Rastreie o nome de arquivo até sua origem usando a pilha de chamadas do traceback. Origens comuns: o campo `filename` de um upload multipart, uma string construída a partir de metadados fornecidos pelo usuário, um campo de resposta de API, uma coluna de banco de dados ou uma listagem de arquivos externa. O local da correção está sempre na origem - não no ponto onde o erro é lançado.
Aplique a sanitização na fronteira de entrada
Adicione uma passagem de sanitização imediatamente depois de o nome entrar no seu sistema - no manipulador de upload, no parser de respostas de API ou onde os dados externos se tornarem pela primeira vez um nome de arquivo. Use `re.sub(r'[<>:"/\\|?*\x00-\x1F]', '-', name)` como substituição de base, depois remova pontos e espaços finais, verifique contra nomes reservados do Windows e trunque para 255 bytes. Use o Validador de Sintaxe Python para verificar sua função sanitizadora quanto a erros de sintaxe antes de implantar.
Valide o nome sanitizado antes da chamada ao sistema de arquivos
Após a sanitização, valide o resultado com o Sanitizador de Nomes de Arquivo para Uploads Multiplataforma para confirmar que nenhum caractere ilegal permanece, que o nome não é um nome de dispositivo reservado do Windows e que o comprimento está dentro do limite de 255 bytes. Isso captura casos extremos que a simples substituição por regex perde - como um nome composto inteiramente de espaços após a remoção, que fica vazio depois do corte.
Sanitizador de Nomes de Arquivo para Uploads Multiplataforma
Cole qualquer nome de arquivo e valide-o contra as regras de Windows, macOS e Linux simultaneamente - identifica caracteres ilegais, nomes reservados, problemas de comprimento e fornece a versão limpa e segura.
Sanitizando nomes de arquivo manualmente em Python
Se você prefere não depender de uma biblioteca de terceiros, pode implementar um sanitizador de nomes de arquivo robusto em Python puro. A abordagem cobre todas as restrições do Windows e multiplataforma sem dependências externas.
A lógica central de sanitização
Um sanitizador de nomes de arquivo completo em Python precisa de cinco operações aplicadas em sequência: normalizar Unicode para a forma composta (NFC) para que caracteres como letras acentuadas sejam armazenados como pontos de código únicos; substituir todos os caracteres ilegais do Windows e caracteres de controle ASCII por um substituto seguro; remover pontos, espaços e hífens iniciais e finais, problemáticos no Windows; verificar contra a lista de nomes de dispositivos reservados do Windows e acrescentar um sufixo se houver correspondência; e por fim truncar para 255 bytes quando codificado em UTF-8.
Lidando com nomes de arquivo Unicode
Aplicações modernas rotineiramente lidam com nomes de arquivo contendo caracteres não ASCII - árabe, chinês, japonês, caracteres latinos acentuados. Todos são legais nos sistemas de arquivos modernos (NTFS, APFS, ext4), mas podem causar problemas quando conversões de codificação acontecem. Um nome válido em UTF-8 pode se corromper se o sistema de arquivos ou o SO estiver configurado para uma codificação legada como Latin-1 ou Windows-1252. Se você encontrar nomes com caracteres embaralhados, passe-os pela Ferramenta de Reparo Unicode e de Codificação para identificar e corrigir o problema de codificação antes da sanitização.
Quando lançar vs. quando autocorrigir
Você tem duas opções quando um caractere ilegal é encontrado: lançar uma exceção (o padrão da biblioteca `python-filenamesanitizer`) ou auto-substituir por um caractere seguro. Para manipuladores de upload, a auto-substituição costuma ser a escolha certa - limpar silenciosamente `invoice: Q1.pdf` para `invoice- Q1.pdf` é melhor que falhar o upload. Para código interno que gera seus próprios nomes, lançar é melhor - um `InvalidCharError` no seu próprio código é um bug a corrigir, não um caso extremo a tratar em silêncio.
Tip
Boas práticas multiplataforma para nomes de arquivo
A estratégia de sanitização mais confiável é um conjunto de regras consistentes aplicado em cada fronteira de entrada, em vez de uma série de correções ad hoc que crescem com o tempo. Essas práticas impedem que `InvalidCharError` e seus parentes apareçam em primeiro lugar.
Construa nomes de arquivo a partir de componentes seguros
Sempre que possível, gere nomes de arquivo a partir de entradas controladas em vez de passar strings fornecidas pelo usuário diretamente. Construa nomes a partir de identificadores sanitizados, UUIDs ou carimbos de data/hora com dois-pontos substituídos: um UUID como `550e8400-e29b-41d4-a716-446655440000` já é seguro em todas as plataformas. Se um nome legível por humanos for necessário, sanitize-o primeiro e depois acrescente o identificador seguro como sufixo para garantir unicidade.
Valide em cada fronteira de SO
- Uploads de arquivos - sanitize o nome enviado antes de salvar, mesmo que seu framework web forneça um campo de nome de arquivo
- Respostas de API - trate qualquer campo de nome de arquivo de uma API externa como não confiável; valide antes de usar
- Registros de banco de dados - nomes armazenados em um banco podem ter sido salvos antes de suas regras de sanitização existirem
- Arquivos de configuração - nomes lidos de arquivos de config podem estar incorretos se a config foi editada por um usuário
- Argumentos de linha de comando - argumentos de caminho fornecidos pelo usuário podem conter expansões de shell ou caracteres especiais
Teste em todas as plataformas de destino
Um bug de nome de arquivo que só se manifesta no Windows é invisível em um ambiente de desenvolvimento apenas Linux. Se sua aplicação rodará no Windows, teste seu código de manipulação de arquivos no Windows - ou adicione um job de CI que execute em um runner Windows. O Sanitizador de Nomes de Arquivo para Uploads Multiplataforma fornece uma verificação agnóstica de SO que você pode executar de qualquer plataforma, tornando-o um substituto prático para testes multi-SO durante o desenvolvimento.
Warning
Validando nomes de arquivo antes de usar
Um sanitizador que auto-substitui caracteres é uma salvaguarda de produção. Um validador que verifica e reporta problemas é uma ferramenta de desenvolvimento e depuração. Ambos têm seu lugar, e usá-los juntos dá a você a cobertura mais forte.
O que a ferramenta Filename Sanitizer verifica
O Sanitizador de Nomes de Arquivo para Uploads Multiplataforma valida nomes de arquivo contra os três principais conjuntos de regras de SO em uma passagem. Ele verifica caracteres ilegais (Windows, macOS, Linux), nomes de dispositivos reservados do Windows, pontos e espaços finais (ilegais no Windows), pontos iniciais (sinal de arquivo oculto no Unix), bytes nulos e caracteres de controle, e o comprimento do nome tanto em caracteres quanto em bytes UTF-8. Ele também mostra a versão segura sanitizada do nome junto com o relatório de validação.
Integrando a validação à CI
Para aplicações que geram nomes de arquivo a partir de templates ou padrões configuráveis, adicione um teste unitário que valide os nomes gerados contra as regras multiplataforma a cada build. Um template de nome que funciona no seu ambiente atual pode produzir um `InvalidCharError` após uma mudança de configuração que introduza dois-pontos no padrão. Detectar isso na CI é significativamente menos custoso do que depurá-lo em produção.
Key takeaways
- `InvalidCharError` dispara quando um nome de arquivo contém um caractere ilegal no SO de destino - a mensagem de erro sempre identifica o caractere específico.
- O Windows proíbe `< > : " / \ | ? *`, caracteres de controle, pontos/espaços finais e nomes reservados (CON, NUL, COM1-9, LPT1-9).
- O Linux só proíbe bytes nulos e barras inclinadas - mas código portátil deve aplicar as regras do Windows universalmente.
- Sempre sanitize nomes de arquivo na fronteira de entrada (manipulador de upload, parser de API) em vez de capturar exceções depois do fato.
- Use o Sanitizador de Nomes de Arquivo para Uploads Multiplataforma para validar qualquer nome contra os três conjuntos de regras de SO em uma passagem.
- Nomes de arquivo Unicode com codificação corrompida precisam da Ferramenta de Reparo Unicode e de Codificação antes da sanitização.
- Auto-substitua caracteres ilegais por hífens em manipuladores de upload; lance exceções no código interno onde nomes inválidos são um bug a corrigir.