Agent Service Reasoner Errors

The Agent SVC Reasoner service coordinates conversations between multiple agents to complete complex tasks. Errors from this service typically indicate that a request between agents was malformed or couldn’t be authenticated, that the agent or session couldn’t be found, or that the orchestration timed out or encountered an internal failure.

A request to the multi-agent orchestration service was malformed or contained invalid parameters. The service received the request but rejected it because of an unsupported message type, invalid input variables, or a request structure it couldn’t process. Retrying the same request won’t help — the request itself needs to be corrected first.

This error occurs when:

• The request was missing required fields or used an unsupported message type.
• The agent’s input variables were invalid — wrong types, unknown variable names, or malformed values.
• The request structure didn’t match the format the service expects.

To resolve this error:

1. Check the detail field in the error response — it includes a specific reason for the rejection.
2. Validate the request against the connected subagent’s configuration before resending.
3. If you constructed the request manually, compare it to a working example from the agent’s published configuration.

If the issue persists, contact Salesforce Customer Support with the following information.

• The trace ID from the error response (instance field, format urn:trace:...)
• The error code: A2A_BAD_REQUEST
• A redacted copy of the request

A request to the multi-agent orchestration service failed validation before it was processed. The request structure or data types didn’t match the expected format. Retrying the same request won’t help — the request needs to be corrected first.

This error occurs when:

• A field has the wrong data type, such as a number where text is expected.
• A required field is missing from the request or the connected subagent’s configuration.
• The request contains malformed content, such as invalid characters or missing brackets.

To resolve this error:

1. Check the detail field in the error response — it identifies which field failed and why.
2. Compare your request to the connected subagent’s published configuration to verify the expected format.
3. If you’re constructing the request manually, validate it before sending.

If the issue persists, contact Salesforce Customer Support with the following information.

• The trace ID from the error response (instance field, format urn:trace:...)
• The error code: A2A_DESERIALIZATION_ERROR
• The full detail text from the error response (it identifies the failing field)
• A redacted copy of the request

The agent, session, or task referenced in the request couldn’t be found. It may not exist, may have expired, or may not be accessible to the authenticated user. Retrying won’t help — the identifier needs to be correct before the request can succeed.

This error occurs when:

• The agent ID doesn’t match a registered agent.
• The task or session ID has expired or was never created.
• The request references a resource that belongs to a different org or user.

To resolve this error:

1. Verify the agent, task, or session ID is correct and hasn’t expired.
2. If the resource was created earlier in a flow, confirm it hasn’t been cleaned up.
3. Confirm you’re authenticated as the user who owns the resource.

If the issue persists, contact Salesforce Customer Support with the following information.

• The trace ID from the error response (instance field, format urn:trace:...)
• The error code: A2A_NOT_FOUND
• The agent ID, task ID, or session ID the request was targeting

The request to the multi-agent orchestration service exceeds the size limit. The service rejected it before processing. Reduce the size of the request before retrying.

This error occurs when:

• A field in the agent’s input variables contains embedded file data that should be passed as a reference instead.
• Input variables have accumulated data across multiple turns and the total has grown too large.
• The full conversation history is being resent with each request instead of relying on the session state.

To resolve this error:

1. Identify which input variables are largest and reduce or remove them.
2. Replace embedded file data with references the agent can look up on demand.
3. Remove accumulated history the agent doesn’t need to see again.
4. Resend the request with the reduced input.

If the issue persists, contact Salesforce Customer Support with the following information.

• The trace ID from the error response (instance field, format urn:trace:...)
• The error code: A2A_PAYLOAD_TOO_LARGE
• The approximate size of the request

The authenticated user doesn’t have permission to perform this action. The identity was confirmed, but the account lacks the required access to the agent or session being requested. Retrying won’t help — the permissions need to change first.

This error occurs when:

• The user doesn’t have the required permission set for the agent.
• Your org’s settings don’t allow this type of access for this user.
• The request is targeting an agent, task, or session that belongs to a different user or org.

To resolve this error:

1. Confirm the user’s permissions include access to the agent they’re trying to reach.
2. If acting on behalf of another user, verify that delegated access is in place.
3. If access should be allowed, contact your Salesforce admin to review the permissions.

If the issue persists, contact Salesforce Customer Support with the following information.

• The trace ID from the error response (instance field, format urn:trace:...)
• The error code: A2A_SECURITY_ERROR
• The agent ID or task ID the request was targeting

This error code indicates an unexpected system error and not an issue with your configuration. If the issue persists, contact Salesforce Customer Support with the following information.

• The trace ID from the error response (instance field, format urn:trace:...)
• The error code: A2A_SYSTEM
• Any context that might help with the investigation, such as when the error occurred, what you or your end user were doing at the time, and whether you’re able to reproduce it

A request to the multi-agent orchestration service timed out before it completed. This is usually a temporary issue. Wait a moment and try again.

This error occurs when:

• A reasoning step or AI model call took longer than the allowed time.
• A platform dependency was slow or under load when the request was made.

To resolve this error:

1. Wait at least 2 seconds, then try again — most timeouts are temporary.
2. If the request consistently times out, try simplifying it — use fewer input variables or a shorter prompt.
3. If retries keep timing out, check trust.salesforce.com for known incidents.

If the issue persists, contact Salesforce Customer Support with the following information.

• The trace ID from the error response (instance field, format urn:trace:...)
• The error code: A2A_TIMEOUT
• Whether retries also timed out

The request to the multi-agent orchestration service couldn’t be authenticated. The service couldn’t verify your identity because authentication credentials were missing or invalid. Retrying without a valid session won’t help.

This error occurs when:

• The request didn’t include the expected authentication credentials or session token.
• The authentication context was removed by a gateway between your client and the service.
• The session token is stale or malformed.

To resolve this error:

1. Check the detail field in the error response — it identifies which part of the authentication context was missing.
2. Re-authenticate to get a fresh session and try again.
3. If you’re connecting through a gateway, verify that authentication headers aren’t being stripped in transit.

If the issue persists, contact Salesforce Customer Support with the following information.

• The trace ID from the error response (instance field, format urn:trace:...)
• The error code: A2A_UNAUTHORIZED
• The detail value from the response (which authentication field was missing)

j

Get Started

Agentforce Examples

Agent Script

Agentforce DX

Agentforce APIs and SDKs

Agentforce Actions

Agentforce Service Errors

Language Detection Service Errors

Agent Service Reasoner Errors

Authentication Service Errors

Model Builder Errors

Interactive Data Science Service Errors

ML Lake Service Errors

Models and Prompts

Headless Agentforce Development