Troubleshooting Document Processing

Q: A large file routes to background processing. What can I tell the user?

Find the Async Request record for the conversation. Status Queued means the work hasn't started; Processing means it's running; Completed means the reply is on the conversation; Failed means the retry budget was used and the error is on the record.

Diagnose by Message Document processing produces a small set of recognisable error messages. This page lists the message a user or admin will see, explains what it means in plain terms, and tells you what to check next.

Where Errors Appear

When document processing goes wrong, the message can show up in three places:

In the agent’s reply, when the issue is something the user can fix (file too large, file type not allowed, file missing).
On the conversation transcript — both as the agent’s reply and as the structured tool result for any tool the agent called.
On the Incident Log when the platform captured a hard failure for an admin to investigate. See AI Incident Logs.

For incidents that aren’t self-explanatory, run Debug with AI on the incident record to get a plain-language explanation and suggested fixes.

Errors a User Sees

“File not found or access denied.”

The platform tried to open the file the user pointed to and couldn’t. Either the file no longer exists, or the running user doesn’t have sharing access to it.

What to check:

Whether the user can open the file directly from Salesforce. If they can’t open it, the agent can’t read it either.
Whether the file was uploaded to the conversation that the user thinks it was — sometimes a file uploaded to a different conversation gets referenced by mistake.
For email-driven runs, whether the inbound email actually produced a stored file (see Email Channel troubleshooting below).

“Unable to access file. Please check permissions.”

The user can see the file’s record but cannot read one of the fields the agent needs to process it. This is almost always a field-level security issue on the user’s permission set or profile.

What to check: the user’s permission set for read access on file records. The Incident Log holds the technical detail of which check failed if the permission set looks correct on the surface.

“Failed to upload file: …”

The file couldn’t be saved into Salesforce. The text after the colon is the underlying Salesforce error.

What to check:

The text after the colon — that’s the actual cause. Common reasons: a validation rule on the file record, an org-level storage limit, or an unsupported file type.
The org’s file-storage usage if the message hints at storage exhaustion.

“File name and content are required.”

Something tried to create a file without supplying both a name and content. End users almost never see this directly — it surfaces when a custom integration calls the upload step incorrectly. Check the calling code or Flow.

“Unable to retrieve file distribution URL.”

The agent needs to share a large file with the model through a temporary link, and the platform couldn’t create that link.

What to check:

Whether the running user has permission to create file distributions (Content Deliveries) in Salesforce.
Whether Content Deliveries are enabled at the org level. If they aren’t, large files will not work; either enable them or keep files within the synchronous size limit.

Errors a File Mapping Tool Produces

These appear in the agent’s reply and on the conversation message’s tool result. For larger imports they also appear on the Scheduled Action record created for the import.

“Missing required parameters: file_content_version_id, target_object, and field_mapping are required.”

The File Mapping tool was invoked but its configuration is incomplete — the target object, the column-to-field mapping, or the file input is missing. Open the tool in the Tool Builder and confirm all four blocks (target object, operation, field mapping, match key for updates) are filled in. See File Mapping Tools.

“CSV file contains no data rows.”

The CSV was readable but contained only a header (or was empty). Check that the user uploaded the file they meant to and not a blank template.

“File import failed: …”

The import threw before any rows could be loaded. The text after the colon is the underlying Salesforce error. Common causes:

Validation rules on the target object firing for the values the file contains.
The user can’t edit a field referenced in the mapping.
For updates, the match key returned no record or returned more than one record for a single row.

“Imported X of Y records into Object.”

Inline import summary — X rows succeeded, the rest failed. This is partial success, not a hard error. The conversation transcript holds the row-level error reasons. Fix the cause for the failed rows and re-run the import for those.

“Imported X records. Y errors.”

Same partial-success picture, but produced by a background batch import. The detail is on the Scheduled Action record created for the import. See Scheduled Actions.

“File import started for X rows into Object. Processing in background. Scheduled Action: <id>”

Not an error — the file was large enough to require background processing. If the user reports “the import didn’t happen” immediately after seeing this, it’s still in progress. Open the Scheduled Action record referenced in the message to track status.

Symptoms Without a Specific Error Message

The agent ignores the file or says it can’t use it

Allow File Upload may be off on the agent. Open the Agent Definition and turn it on.
The file’s extension may not be on the Allowed File Extensions Platform Setting.
The file may be larger than Max File Size (MB).
For CSVs, the content may exceed Max CSV Characters.
The agent may not have any tool that can act on the file. Without a tool to act on extracted data, the agent will read the file but can’t do anything with it. See Document Processing.

Files arrive in Salesforce but never reach the agent

On the inbound-email channel two filters can drop files silently:

Very small attachments are filtered out as logos or signatures.
Attachments whose extension isn’t on the allowlist are dropped.

Both of these produce Incident Log entries when relevant. See Troubleshooting the Email Channel.

Large file requests appear to hang

Large files are processed in the background. The user sees a waiting state; the agent’s reply lands on the conversation when the background work completes. If the wait seems excessive, find the Async Request record for the conversation and check its status. See Async Agent Processing.

How to Walk Through a Failure

Read the exact message.
The wording matches the table above. Matching it tells you which part of the pipeline produced the error.
Open the conversation.
The user message, the file attachment, the tool call (if any) and the raw tool result are all on the conversation. The tool result usually carries more detail than the agent’s reply.
Check the Incident Log.
For non-trivial failures, an incident captures the technical detail that the user-facing message hides.
Run Debug with AI.
Multi-turn analysis usually narrows the cause faster than reading the raw error.
Verify in Runtime Preview.
If the cause was agent configuration, open Agent Runtime Preview after the change to confirm what the agent now loads.

Frequently Asked Questions

If the file failed validation (size, extension), the upload was rejected before the conversation message was created — the user should have seen an error explaining why. If the file appears to have succeeded but isn’t showing on the conversation, check the file’s sharing — you may not have read access even though the user does.

Look at the row-level errors in the tool result. Validation rules and field-level security often cause every row to fail with the same error. Once you fix the root cause, the import will succeed.

Imports run under the running user’s permissions. The other user’s field-level security on the mapped fields, and their sharing on the records being updated, are different from yours.

Find the Async Request record for the conversation. Status Queued means the work hasn’t started; Processing means it’s running; Completed means the reply is on the conversation; Failed means the retry budget was used and the error is on the record.

Most often the agent isn’t configured to use files — either Allow File Upload is off, or the agent has no tool that takes file input. Both are visible on the Agent Definition. See File Upload.

On the matching Incident Log record. The user-facing message is intentionally short; the underlying cause and stack trace are captured on the incident.

Next Steps

Read AI Incident Logs for the underlying record structure, or Troubleshooting the Email Channel for failures specific to inbound and outbound email.

← Previous: Debug with AI

Next: Troubleshooting the Email Channel →