Como Solucionar Relatório de Migração Mostrando Falha por Caracteres Não Suportados

Ao executar uma migração do SharePoint usando a Ferramenta de Migração do SharePoint (SPMT) ou a API de Migração, o relatório de migração pode mostrar itens como falhos devido a caracteres não suportados em nomes de arquivos, pastas ou metadados. O SharePoint Online impõe regras rígidas de nomenclatura que rejeitam caracteres como #, %, &, {, ~ e espaços à direita. Essas falhas podem impedir a conclusão da migração ou causar perda parcial de dados. Este artigo explica por que caracteres não suportados causam falhas, como identificá-los no relatório de migração e as etapas exatas para corrigir os nomes dos arquivos para que sua migração possa ser concluída com sucesso.

Por que Caracteres Não Suportados Causam Falhas na Migração

O SharePoint Online usa as convenções de nomenclatura do sistema de arquivos Windows, além de restrições adicionais para acesso baseado na web. Quando um nome de arquivo ou pasta contém um caractere não permitido, a Ferramenta de Migração do SharePoint não consegue criar o item na biblioteca de destino. O mecanismo de migração registra o arquivo como Falhou com um código de erro como UnsupportedFileNameCharacters ou InvalidFolderName.

A lista completa de caracteres não suportados em nomes de arquivos e pastas do SharePoint Online inclui:

• ~ til
• " aspas duplas
• # cerquilha
• % porcentagem
• & e comercial
• asterisco
• : dois pontos
• < menor que
• > maior que
• ? ponto de interrogação
• / barra
• \ barra invertida
• { chave esquerda
• | barra vertical
• } chave direita
• Espaços no início ou no final
• Pontos no final

Essas restrições se aplicam a nomes de arquivos, nomes de pastas e campos de metadados, como título ou descrição. A ferramenta de migração não renomeia arquivos automaticamente. Você deve corrigir os nomes antes ou depois da tentativa de migração.

Etapas para Identificar e Corrigir Caracteres Não Suportados no Relatório de Migração

1. Abra o Relatório de Migração
   Após a conclusão de um trabalho de migração, abra a Ferramenta de Migração do SharePoint. Vá para Gerenciador de Migração e selecione o trabalho que falhou. Clique em Exibir Relatório para baixar o arquivo CSV. O relatório contém colunas para Caminho de Origem, Caminho de Destino, Status e Erro. Filtre a coluna Status para mostrar apenas as linhas com Falhou.
2. Identifique os Caracteres Não Suportados
   No relatório CSV, observe a coluna Erro. Se a mensagem de erro contiver UnsupportedFileNameCharacters ou InvalidFolderName, anote o caminho completo de origem. Copie o nome do arquivo ou pasta para um editor de texto. Use a lista de caracteres acima para encontrar o caractere problemático. Os culpados comuns são # em nomes de arquivos com números de versão, & em nomes de projetos e espaços à direita de entrada do usuário.
3. Renomeie os Arquivos ou Pastas na Origem
   No seu servidor de arquivos local ou compartilhamento de rede, navegue até a pasta de origem. Renomeie cada arquivo ou pasta que contenha caracteres não suportados. Substitua cada caractere inválido por uma alternativa válida. Por exemplo, substitua # por No, substitua & por e e remova espaços à direita. Mantenha o nome curto e legível. Não use caracteres que ainda sejam inválidos.
4. Use PowerShell para Verificar e Renomear Automaticamente
   Se você tiver muitos arquivos, use um script PowerShell para encontrá-los e renomeá-los. Abra o PowerShell como administrador e execute este script que substitui caracteres inválidos por um hífen:

   
Get-ChildItem -Path "C:\PastaOrigem\" -Recurse | Where-Object { $_.Name -match '[~"#%&:<>?/\\{|} ]' } | ForEach-Object {
  $novoNome = $_.Name -replace '[~"#%&:<>?/\\{|} ]', '-';
  Rename-Item -Path $_.FullName -NewName $novoNome
}

   Substitua C:\PastaOrigem pelo caminho real da sua origem. Este script substitui qualquer caractere inválido por um hífen. Teste em uma pasta pequena primeiro.

5. Execute Novamente o Trabalho de Migração
   Após renomear os arquivos, volte à Ferramenta de Migração do SharePoint. Selecione a mesma origem e destino. A ferramenta verificará a origem novamente. Como os nomes agora são válidos, a migração deve ser concluída sem o erro de caractere não suportado. Monitore o novo relatório para confirmar que todos os itens passaram.
6. Verifique os Arquivos no SharePoint
   Após a conclusão da migração, abra a biblioteca de documentos do SharePoint em um navegador. Verifique se todos os arquivos aparecem com os novos nomes. Abra alguns arquivos para confirmar que o conteúdo está intacto. Se você usou um script, verifique se nenhum nome de arquivo foi truncado ou duplicado.

Se a Migração Ainda Mostrar Falhas Após a Renomeação

"O nome do arquivo contém um ponto ou espaço à direita"

O SharePoint não permite nomes de arquivo que terminem com um ponto ou espaço. Por exemplo, Relatório..docx ou Rascunho .docx. Esses caracteres são invisíveis em muitos exploradores de arquivos. Para corrigir isso, use PowerShell para remover pontos e espaços à direita. O script acima substituirá espaços por hífens, mas não removerá pontos à direita. Adicione esta linha após o comando de renomeação:

Rename-Item -Path $_.FullName -NewName ($_.BaseName.TrimEnd('. ') + $_.Extension)

"O nome do arquivo é muito longo"

O SharePoint Online tem um comprimento máximo de caminho de 400 caracteres. Se o caminho do arquivo (incluindo nomes de pastas) exceder esse limite, a migração falha. A mensagem de erro pode dizer PathTooLong. Encurte nomes de pastas ou remova pastas aninhadas desnecessárias. Mova arquivos profundos para mais perto da raiz da biblioteca.

"O relatório de migração não mostra erros, mas alguns arquivos estão faltando"

Se o relatório disser que todos os itens foram bem-sucedidos, mas os arquivos estão faltando, verifique a coluna Pulado no relatório CSV. Os arquivos podem ser pulados se o destino já tiver um arquivo com o mesmo nome. Exclua o arquivo existente ou use a opção Sobrescrever nas configurações de migração.

Correção Manual vs. Automatizada: Principais Diferenças

Item	Correção Manual	Correção Automatizada com PowerShell
Tempo necessário	Alto para muitos arquivos	Baixo após configuração do script
Risco de erro humano	Alto	Baixo se o script for testado
Controle sobre novos nomes	Controle total por arquivo	Usa uma regra de substituição consistente
Melhor para	Poucos arquivos com necessidades complexas de nomenclatura	Centenas ou milhares de arquivos

Após corrigir todos os caracteres não suportados, seu relatório de migração deve mostrar zero falhas para essa categoria. Execute novamente o trabalho de migração para os arquivos corrigidos. Se ainda houver falhas, verifique outros erros, como nomes duplicados ou problemas de permissão. A Ferramenta de Migração do SharePoint registra cada erro com um código específico, que você pode consultar na documentação da Microsoft. Use o recurso Exportar relatório para manter um registro das migrações bem-sucedidas para auditoria.