Solução de problemas de processamento de documentos
Onde os erros aparecem
Quando o processamento de documentos dá errado, a mensagem pode aparecer em três lugares:
- Na resposta do agente, quando o problema é algo que o usuário pode corrigir (arquivo muito grande, tipo de arquivo não permitido, arquivo ausente).
- Na transcrição da conversa — tanto como resposta do agente quanto como resultado estruturado da ferramenta para qualquer ferramenta que o agente tenha chamado.
- No Registro de Incidentes de IA, quando a plataforma capturou uma falha grave para um administrador investigar. Veja Registros de incidentes de IA.
Para incidentes que não são autoexplicativos, execute Depuração com IA no registro do incidente para obter uma explicação em linguagem simples e sugestões de correção.
Erros que um usuário vê
As mensagens desta página são citadas em inglês de propósito. Os rótulos de erro de arquivos da REDA AI não são traduzidos, então é exatamente isso que você verá na tela, qualquer que seja o idioma do seu usuário. Elas são citadas como estão para que você possa procurar nesta página o texto que tem diante de si; abaixo de cada uma vêm a tradução e a explicação.
“File not found or access denied.”
Em português: “Arquivo não encontrado ou acesso negado.”
A plataforma tentou abrir o arquivo que o usuário indicou e não conseguiu. Ou o arquivo não existe mais, ou o usuário em execução não tem acesso de compartilhamento a ele.
O que verificar:
- Se o usuário consegue abrir o arquivo diretamente pelo Salesforce. Se ele não conseguir abri-lo, o agente também não conseguirá lê-lo.
- Se o arquivo foi enviado para a conversa que o usuário acredita que foi — às vezes um arquivo enviado para outra conversa é referenciado por engano.
- Para execuções originadas por e-mail, se o e-mail recebido de fato gerou um arquivo armazenado (veja a solução de problemas do Canal de E-mail abaixo).
“Unable to access file. Please check permissions.”
Em português: “Não é possível acessar o arquivo. Verifique as permissões.”
O usuário consegue ver o registro do arquivo, mas não consegue ler um dos campos que o agente precisa para processá-lo. Isso quase sempre é um problema de segurança em nível de campo no conjunto de permissões ou no perfil do usuário.
O que verificar: o conjunto de permissões do usuário quanto ao acesso de leitura em registros de arquivo. O Registro de Incidentes de IA contém o detalhe técnico de qual verificação falhou, caso o conjunto de permissões pareça correto à primeira vista.
“Failed to upload file: …”
Em português: “Falha ao enviar o arquivo: …”
O arquivo não pôde ser salvo no Salesforce. O texto após os dois-pontos é o erro subjacente do Salesforce.
O que verificar:
- O texto após os dois-pontos — essa é a causa real. Motivos comuns: uma regra de validação no registro do arquivo, um limite de armazenamento em nível de organização, ou um tipo de arquivo não suportado.
- O uso de armazenamento de arquivos da organização, se a mensagem sugerir esgotamento de armazenamento.
“File name and content are required.”
Em português: “Nome e conteúdo do arquivo são obrigatórios.”
Algo tentou criar um arquivo sem fornecer nome e conteúdo. Usuários finais quase nunca veem isso diretamente — ele aparece quando uma integração personalizada chama a etapa de envio de forma incorreta. Verifique o código de chamada ou o Fluxo.
“Unable to retrieve file distribution URL.”
Em português: “Não é possível obter a URL de distribuição do arquivo.”
O agente precisa compartilhar um arquivo grande com o modelo por meio de um link temporário, e a plataforma não conseguiu criar esse link.
O que verificar:
- Se o usuário em execução tem permissão para criar distribuições de arquivo (Content Deliveries) no Salesforce.
- Se as Content Deliveries estão habilitadas em nível de organização. Se não estiverem, arquivos grandes não funcionarão; habilite-as ou mantenha os arquivos dentro do limite de tamanho síncrono.
Erros produzidos por uma Ferramenta de Mapeamento de Arquivos
Esses erros aparecem na resposta do agente e no resultado da ferramenta na mensagem da conversa. Para importações maiores, também aparecem no registro de Ação Agendada de IA criado para a importação.
“Missing required parameters: file_content_version_id, target_object, and field_mapping are required.”
Em português: “Parâmetros obrigatórios ausentes: file_content_version_id, target_object e field_mapping são obrigatórios.”
A ferramenta de Mapeamento de Arquivos foi chamada, mas sua configuração está incompleta — falta o objeto de destino, o mapeamento de coluna para campo, ou a entrada de arquivo. Abra a ferramenta no Tool Builder e confirme que os quatro blocos (objeto de destino, operação, mapeamento de campos, chave de correspondência para atualizações) estão preenchidos. Veja Ferramentas de mapeamento de arquivos.
“CSV file contains no data rows.”
Em português: “O arquivo CSV não contém linhas de dados.”
O CSV era legível, mas continha apenas um cabeçalho (ou estava vazio). Verifique se o usuário enviou o arquivo pretendido e não um modelo em branco.
“File import failed: …”
Em português: “Falha na importação do arquivo: …”
A importação falhou antes que qualquer linha pudesse ser carregada. O texto após os dois-pontos é o erro subjacente do Salesforce. Causas comuns:
- Regras de validação no objeto de destino sendo acionadas pelos valores contidos no arquivo.
- O usuário não pode editar um campo referenciado no mapeamento.
- Para atualizações, a chave de correspondência não retornou nenhum registro ou retornou mais de um registro para uma única linha.
“Imported X of Y records into Object.”
Em português: “Foram importados X de Y registros em Objeto.”
Resumo da importação em linha — X linhas tiveram sucesso, o restante falhou. Isso é sucesso parcial, não um erro grave. A transcrição da conversa contém os motivos de erro no nível da linha. Corrija a causa das linhas com falha e execute novamente a importação para elas.
“Imported X records. Y errors.”
Em português: “Foram importados X registros. Y erros.”
Mesmo cenário de sucesso parcial, mas produzido por uma importação em lote em segundo plano. O detalhe está no registro de Ação Agendada de IA criado para a importação. Veja Ações Agendadas.
“File import started for X rows into Object. Processing in background. Scheduled Action: <id>”
Em português: “Importação de arquivo iniciada para X linhas em Objeto. Processando em segundo plano. Ação agendada: <id>”
Não é um erro — o arquivo era grande o suficiente para exigir processamento em segundo plano. Se o usuário relatar que “a importação não aconteceu” logo depois de ver essa mensagem, ela ainda está em andamento. Abra o registro de Ação Agendada de IA referenciado na mensagem para acompanhar o status.
Sintomas sem uma mensagem de erro específica
O agente ignora o arquivo ou diz que não pode usá-lo
- A opção Permitir Envio de Arquivo pode estar desativada no agente. Abra a Definição de Agente e ative-a.
- A extensão do arquivo pode não estar na Configuração de Plataforma Allowed File Extensions (extensões de arquivo permitidas).
- O arquivo pode ser maior que Max File Size (MB) (tamanho máximo de arquivo).
- Para CSVs, o conteúdo pode exceder Max CSV Characters (máximo de caracteres do CSV).
- O agente pode não ter nenhuma ferramenta capaz de agir sobre o arquivo. Sem uma ferramenta para agir sobre os dados extraídos, o agente lerá o arquivo, mas não poderá fazer nada com ele. Veja Processamento de Documentos.
Arquivos chegam ao Salesforce, mas nunca alcançam o agente
No canal de e-mail recebido, dois filtros podem descartar arquivos silenciosamente:
- Anexos muito pequenos são filtrados como logotipos ou assinaturas.
- Anexos cuja extensão não está na lista permitida são descartados.
Ambos os casos geram entradas no Registro de Incidentes de IA quando relevante. Veja Solução de problemas do canal de e-mail.
Solicitações de arquivos grandes parecem travar
Arquivos grandes são processados em segundo plano. O usuário vê um estado de espera; a resposta do agente chega à conversa quando o trabalho em segundo plano é concluído. Se a espera parecer excessiva, localize o registro de Solicitação Assíncrona da conversa e verifique seu status. Veja Processamento assíncrono de agentes.
Como analisar uma falha
-
Leia a mensagem exata.
O texto corresponde à tabela acima. Encontrar a correspondência informa qual parte do pipeline gerou o erro.
-
Abra a conversa.
A mensagem do usuário, o anexo de arquivo, a chamada de ferramenta (se houver) e o resultado bruto da ferramenta estão todos na conversa. O resultado da ferramenta geralmente traz mais detalhes do que a resposta do agente.
-
Verifique o Registro de Incidentes de IA.
Para falhas não triviais, um incidente captura o detalhe técnico que a mensagem voltada ao usuário oculta.
-
Execute a Depuração com IA.
A análise em múltiplas etapas geralmente reduz a causa mais rápido do que ler o erro bruto.
-
Verifique na Pré-visualização de Execução do Agente.
Se a causa foi a configuração do agente, abra a Pré-visualização de Execução do Agente após a alteração para confirmar o que o agente agora carrega.
Perguntas frequentes
Se o arquivo falhou na validação (tamanho, extensão), o envio foi rejeitado antes de a mensagem da conversa ser criada — o usuário deveria ter visto um erro explicando o motivo. Se o arquivo parece ter sido enviado com sucesso, mas não aparece na conversa, verifique o compartilhamento do arquivo — você pode não ter acesso de leitura mesmo que o usuário tenha.
Observe os erros no nível da linha no resultado da ferramenta. Regras de validação e segurança em nível de campo costumam fazer com que todas as linhas falhem com o mesmo erro. Depois de corrigir a causa raiz, a importação será concluída com sucesso.
As importações são executadas sob as permissões do usuário em execução. A segurança em nível de campo do outro usuário nos campos mapeados, e o compartilhamento dele nos registros que estão sendo atualizados, são diferentes dos seus.
Localize o registro de Solicitação Assíncrona da conversa. Status Na fila significa que o trabalho ainda não começou; Em processamento significa que está em execução; Concluído significa que a resposta está na conversa; Falhou significa que o orçamento de novas tentativas foi usado e o erro está no registro.
Na maioria das vezes, o agente não está configurado para usar arquivos — ou a opção Permitir Envio de Arquivo está desativada, ou o agente não tem nenhuma ferramenta que aceite entrada de arquivo. Ambos são visíveis na Definição de Agente. Veja Upload de Arquivos.
No registro correspondente de Registro de Incidentes de IA. A mensagem voltada ao usuário é intencionalmente curta; a causa subjacente e o stack trace são capturados no incidente.
Próximos passos
Leia Registros de incidentes de IA para entender a estrutura de registro subjacente, ou Solução de problemas do canal de e-mail para falhas específicas de e-mail recebido e enviado.