Solución de problemas de procesamiento de documentos
Dónde aparecen los errores
Cuando el procesamiento de documentos falla, el mensaje puede aparecer en tres lugares:
- En la respuesta del agente, cuando el problema es algo que el usuario puede corregir (archivo demasiado grande, tipo de archivo no permitido, archivo faltante).
- En la transcripción de la conversación — tanto como respuesta del agente como en el resultado estructurado de la herramienta para cualquier herramienta que el agente haya invocado.
- En el Registro de incidentes de IA cuando la plataforma capturó una falla grave para que la investigue un administrador. Consulta Registros de incidentes de IA.
Para los incidentes que no se explican por sí solos, ejecuta Depurar con IA sobre el registro del incidente para obtener una explicación en lenguaje sencillo y correcciones sugeridas.
Errores que ve un usuario
Los mensajes de esta página se citan en inglés a propósito. Las etiquetas de error de archivos de REDA AI no están traducidas, así que es exactamente eso lo que verás en pantalla, sea cual sea el idioma de tu usuario. Se citan tal cual para que puedas buscar en esta página el texto que tienes delante; debajo de cada uno encontrarás la traducción y la explicación.
“File not found or access denied.”
En español: «Archivo no encontrado o acceso denegado.»
La plataforma intentó abrir el archivo al que apuntaba el usuario y no pudo. O bien el archivo ya no existe, o bien el usuario en ejecución no tiene acceso compartido a él.
Qué revisar:
- Si el usuario puede abrir el archivo directamente desde Salesforce. Si no puede abrirlo, el agente tampoco puede leerlo.
- Si el archivo se cargó en la conversación que el usuario cree — a veces un archivo cargado en otra conversación se referencia por error.
- En ejecuciones originadas por correo, si el correo entrante realmente produjo un archivo almacenado (consulta la solución de problemas del canal de correo más abajo).
“Unable to access file. Please check permissions.”
En español: «No se puede acceder al archivo. Revisa los permisos.»
El usuario puede ver el registro del archivo, pero no puede leer uno de los campos que el agente necesita para procesarlo. Esto casi siempre es un problema de seguridad a nivel de campo en el conjunto de permisos o el perfil del usuario.
Qué revisar: el conjunto de permisos del usuario para el acceso de lectura en los registros de archivos. El Registro de incidentes de IA contiene el detalle técnico de qué verificación falló si el conjunto de permisos parece correcto a primera vista.
“Failed to upload file: …”
En español: «No se pudo cargar el archivo: …»
El archivo no se pudo guardar en Salesforce. El texto después de los dos puntos es el error subyacente de Salesforce.
Qué revisar:
- El texto después de los dos puntos — esa es la causa real. Motivos habituales: una regla de validación en el registro del archivo, un límite de almacenamiento a nivel de organización o un tipo de archivo no admitido.
- El uso de almacenamiento de archivos de la organización si el mensaje sugiere que se agotó el almacenamiento.
“File name and content are required.”
En español: «El nombre y el contenido del archivo son obligatorios.»
Algo intentó crear un archivo sin proporcionar tanto un nombre como un contenido. Los usuarios finales casi nunca ven esto directamente — surge cuando una integración personalizada invoca el paso de carga de forma incorrecta. Revisa el código o el flujo que hace la llamada.
“Unable to retrieve file distribution URL.”
En español: «No se puede recuperar la URL de distribución del archivo.»
El agente necesita compartir un archivo grande con el modelo mediante un enlace temporal, y la plataforma no pudo crear ese enlace.
Qué revisar:
- Si el usuario en ejecución tiene permiso para crear distribuciones de archivos (entregas de contenido) en Salesforce.
- Si las entregas de contenido están habilitadas a nivel de organización. Si no lo están, los archivos grandes no funcionarán; habilítalas o mantén los archivos dentro del límite de tamaño síncrono.
Errores que produce una herramienta de mapeo de archivos
Estos aparecen en la respuesta del agente y en el resultado de la herramienta del mensaje de la conversación. En importaciones más grandes, también aparecen en el registro de Acción programada de IA creado para la importación.
“Missing required parameters: file_content_version_id, target_object, and field_mapping are required.”
En español: «Faltan parámetros obligatorios: file_content_version_id, target_object y field_mapping son obligatorios.»
La herramienta de mapeo de archivos se invocó, pero su configuración está incompleta — falta el objeto de destino, el mapeo de columna a campo o el archivo de entrada. Abre la herramienta en el generador de herramientas y confirma que los cuatro bloques (objeto de destino, operación, mapeo de campos, clave de coincidencia para actualizaciones) estén completos. Consulta Herramientas de mapeo de archivos.
“CSV file contains no data rows.”
En español: «El archivo CSV no contiene filas de datos.»
El CSV se pudo leer, pero solo contenía un encabezado (o estaba vacío). Verifica que el usuario haya cargado el archivo que pretendía y no una plantilla en blanco.
“File import failed: …”
En español: «La importación del archivo falló: …»
La importación falló antes de que se pudiera cargar cualquier fila. El texto después de los dos puntos es el error subyacente de Salesforce. Causas habituales:
- Reglas de validación en el objeto de destino que se activan para los valores que contiene el archivo.
- El usuario no puede editar un campo referenciado en el mapeo.
- En actualizaciones, la clave de coincidencia no devolvió ningún registro o devolvió más de un registro para una sola fila.
“Imported X of Y records into Object.”
En español: «Se importaron X de Y registros en Objeto.»
Resumen de importación en línea — X filas se completaron correctamente y el resto falló. Esto es un éxito parcial, no un error grave. La transcripción de la conversación contiene los motivos de error por fila. Corrige la causa de las filas fallidas y vuelve a ejecutar la importación para esas filas.
“Imported X records. Y errors.”
En español: «Se importaron X registros. Y errores.»
La misma imagen de éxito parcial, pero producida por una importación por lotes en segundo plano. El detalle está en el registro de Acción programada de IA creado para la importación. Consulta Acciones programadas.
“File import started for X rows into Object. Processing in background. Scheduled Action: <id>”
En español: «Se inició la importación del archivo para X filas en Objeto. Procesando en segundo plano. Acción programada: <id>»
No es un error — el archivo era lo bastante grande como para requerir procesamiento en segundo plano. Si el usuario informa que “la importación no se realizó” inmediatamente después de ver esto, todavía está en curso. Abre el registro de Acción programada de IA referenciado en el mensaje para hacer seguimiento del estado.
Síntomas sin un mensaje de error específico
El agente ignora el archivo o dice que no puede usarlo
- Permitir carga de archivos puede estar desactivado en el agente. Abre la Definición de agente y actívalo.
- La extensión del archivo puede no estar en la configuración de la plataforma Extensiones de archivo permitidas.
- El archivo puede ser más grande que Tamaño máximo de archivo (MB).
- En los CSV, el contenido puede superar Máximo de caracteres CSV.
- El agente puede no tener ninguna herramienta que pueda actuar sobre el archivo. Sin una herramienta que actúe sobre los datos extraídos, el agente leerá el archivo, pero no podrá hacer nada con él. Consulta Procesamiento de documentos.
Los archivos llegan a Salesforce pero nunca llegan al agente
En el canal de correo entrante, dos filtros pueden descartar archivos de forma silenciosa:
- Los archivos adjuntos muy pequeños se filtran por considerarse logotipos o firmas.
- Los archivos adjuntos cuya extensión no está en la lista de permitidos se descartan.
Ambos generan entradas en el Registro de incidentes de IA cuando corresponde. Consulta Solución de problemas del canal de correo.
Las solicitudes de archivos grandes parecen quedarse colgadas
Los archivos grandes se procesan en segundo plano. El usuario ve un estado de espera; la respuesta del agente llega a la conversación cuando se completa el trabajo en segundo plano. Si la espera parece excesiva, busca el registro de Solicitud asíncrona de la conversación y revisa su estado. Consulta Procesamiento asíncrono de agentes.
Cómo recorrer una falla paso a paso
-
Lee el mensaje exacto.
La redacción coincide con la tabla anterior. Al hacerla coincidir sabrás qué parte del proceso produjo el error.
-
Abre la conversación.
El mensaje del usuario, el archivo adjunto, la llamada a la herramienta (si la hay) y el resultado sin procesar de la herramienta están todos en la conversación. El resultado de la herramienta suele contener más detalle que la respuesta del agente.
-
Revisa el Registro de incidentes de IA.
En las fallas no triviales, un incidente captura el detalle técnico que el mensaje dirigido al usuario oculta.
-
Ejecuta Depurar con IA.
El análisis de varios turnos suele acotar la causa más rápido que leer el error sin procesar.
-
Verifica en la Vista previa de ejecución.
Si la causa fue la configuración del agente, abre Vista previa de ejecución del agente después del cambio para confirmar lo que el agente carga ahora.
Preguntas frecuentes
Si el archivo no pasó la validación (tamaño, extensión), la carga se rechazó antes de crear el mensaje de la conversación — el usuario debería haber visto un error que explica por qué. Si parece que el archivo se cargó correctamente pero no aparece en la conversación, revisa el uso compartido del archivo — es posible que tú no tengas acceso de lectura aunque el usuario sí lo tenga.
Revisa los errores por fila en el resultado de la herramienta. Las reglas de validación y la seguridad a nivel de campo suelen provocar que todas las filas fallen con el mismo error. Una vez que corrijas la causa de fondo, la importación se realizará correctamente.
Las importaciones se ejecutan con los permisos del usuario en ejecución. La seguridad a nivel de campo del otro usuario sobre los campos mapeados, y su uso compartido sobre los registros que se actualizan, son distintos de los tuyos.
Busca el registro de Solicitud asíncrona de la conversación. El estado En cola significa que el trabajo no ha comenzado; En procesamiento significa que se está ejecutando; Completado significa que la respuesta está en la conversación; Con error significa que se agotó el presupuesto de reintentos y el error está en el registro.
Lo más habitual es que el agente no esté configurado para usar archivos — o bien Permitir carga de archivos está desactivado, o bien el agente no tiene ninguna herramienta que reciba archivos como entrada. Ambos se ven en la Definición de agente. Consulta Carga de archivos.
En el Registro de incidentes de IA correspondiente. El mensaje dirigido al usuario es intencionalmente breve; la causa subyacente y la traza de la pila se capturan en el incidente.
Próximos pasos
Lee Registros de incidentes de IA para conocer la estructura de registros subyacente, o Solución de problemas del canal de correo para las fallas específicas del correo entrante y saliente.