Skip to content

Agentic AI: Document known error codes #7174

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 3, 2025
Merged

Agentic AI: Document known error codes #7174

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
efbc9ce
docs(agentic-ai): document AI Agent error codes
maff Oct 24, 2025
127ae5c
docs(agentic-ai): document AI Agent error codes (8.8)
maff Oct 24, 2025
7c40f66
docs(agentic-ai): Apply review suggestions
maff Nov 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ...omponents/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,6 @@ See [event handling](#configuration-event-handling) for more information.
<ConfigurationEventHandling />
<ConfigurationResponse type="process" />
<ConfigurationOutputMappingProcess />
<ConfigurationErrorHandling />
<ConfigurationErrorHandling type="process" />
<ConfigurationRetries />
<ConfigurationExecutionListeners />
2 changes: 1 addition & 1 deletion docs/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Implement an AI agent using an AI Agent connector applied to a service task, pai
<ConfigurationLimits />
<ConfigurationResponse />
<ConfigurationOutputMappingTask />
<ConfigurationErrorHandling />
<ConfigurationErrorHandling type="task" />
<ConfigurationRetries />
<ConfigurationExecutionListeners />

Expand Down
7 changes: 7 additions & 0 deletions ...out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
The AI Agent Task generates the following error codes when creating the tool schema from the process definition XML:

| Error code | Description |
| :----------------------------------- | :------------------------------------------------------------------------------------------------------- |
| `AD_HOC_SUB_PROCESS_XML_FETCH_ERROR` | The process definition XML could not be fetched. |
| `AD_HOC_SUB_PROCESS_NOT_FOUND` | The ad-hoc sub-process with the configured ID could not be found in the process definition XML. |
| `AD_HOC_TOOL_DEFINITION_INVALID` | The ad-hoc sub-process contains invalid tool definitions which can't be transformed into a tool schema. |
15 changes: 15 additions & 0 deletions ...s/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,22 @@
import ConfigurationErrorCodesTask from './\_error-codes-task.md';

### Error handling

If an error occurs, the AI Agent connector throws an error and includes the error response in the error variable in Operate.

| Field | Required | Description |
| :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Error expression | No | You can handle an AI Agent connector error using an Error Boundary Event and [error expressions](/components/connectors/use-connectors/index.md#error-expression). |

In the error expression, you can handle the following error codes emitted by the AI Agent connector to respond to specific situations. For example, you can map a specific error code to a BPMN error and model
your process accordingly.

| Error code | Description |
| :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `FAILED_MODEL_CALL` | The call to the LLM API failed, for example due to misconfiguration or wrong credentials. The error message contains additional details. |
| `FAILED_TO_PARSE_RESPONSE_CONTENT` | The AI Agent was configured to parse the LLM response as JSON, but the parsing failed. |
| `MAXIMUM_NUMBER_OF_MODEL_CALLS_REACHED` | The AI Agent reached the maximum number of configured model calls. |
| `NO_USER_MESSAGE_CONTENT` | Indicates that no user message content, either from a user prompt or a document, was provided to the agent. |
| `TOOL_CALL_RESULTS_ON_EMPTY_CONTEXT` | Tool call results were passed to the AI Agent despite the context being empty, which typically indicates a misconfiguration of the agent context. |

{props.type === "task" && <ConfigurationErrorCodesTask />}
2 changes: 1 addition & 1 deletion ...omponents/connectors/out-of-the-box-connectors/agentic-ai-aiagent-subprocess.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,6 @@ See [event handling](#configuration-event-handling) for more information.
<ConfigurationEventHandling />
<ConfigurationResponse type="process" />
<ConfigurationOutputMappingProcess />
<ConfigurationErrorHandling />
<ConfigurationErrorHandling type="process" />
<ConfigurationRetries />
<ConfigurationExecutionListeners />
2 changes: 1 addition & 1 deletion ...-8.8/components/connectors/out-of-the-box-connectors/agentic-ai-aiagent-task.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Implement an AI agent using an AI Agent connector applied to a service task, pai
<ConfigurationLimits />
<ConfigurationResponse />
<ConfigurationOutputMappingTask />
<ConfigurationErrorHandling />
<ConfigurationErrorHandling type="task" />
<ConfigurationRetries />
<ConfigurationExecutionListeners />

Expand Down
7 changes: 7 additions & 0 deletions ...out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-codes-task.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
The AI Agent Task generates the following error codes when creating the tool schema from the process definition XML:

| Error code | Description |
| :----------------------------------- | :------------------------------------------------------------------------------------------------------- |
| `AD_HOC_SUB_PROCESS_XML_FETCH_ERROR` | The process definition XML could not be fetched. |
| `AD_HOC_SUB_PROCESS_NOT_FOUND` | The ad-hoc sub-process with the configured ID could not be found in the process definition XML. |
| `AD_HOC_TOOL_DEFINITION_INVALID` | The ad-hoc sub-process contains invalid tool definitions which can't be transformed into a tool schema. |
14 changes: 14 additions & 0 deletions ...s/out-of-the-box-connectors/agentic-ai/aiagent/configuration/_error-handling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,21 @@
import ConfigurationErrorCodesTask from './\_error-codes-task.md';

### Error handling

If an error occurs, the AI Agent connector throws an error and includes the error response in the error variable in Operate.

| Field | Required | Description |
| :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Error expression | No | You can handle an AI Agent connector error using an Error Boundary Event and [error expressions](/components/connectors/use-connectors/index.md#error-expression). |

In the error expression, you can handle the following error codes emitted by the AI Agent connector to respond to specific situations. For example, you can map a specific error code to a BPMN error and model
your process accordingly.

| Error code | Description |
| :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `FAILED_TO_PARSE_RESPONSE_CONTENT` | The AI Agent was configured to parse the LLM response as JSON, but the parsing failed. |
| `MAXIMUM_NUMBER_OF_MODEL_CALLS_REACHED` | The AI Agent reached the maximum number of configured model calls. |
| `NO_USER_MESSAGE_CONTENT` | Indicates that no user message content, either from a user prompt or a document, was provided to the agent. |
| `TOOL_CALL_RESULTS_ON_EMPTY_CONTEXT` | Tool call results were passed to the AI Agent despite the context being empty, which typically indicates a misconfiguration of the agent context. |

{props.type === "task" && <ConfigurationErrorCodesTask />}
Loading