Troubleshooting AI agents

AI agents are powerful tools, but sometimes runs can fail. This guide provides a compact quick path plus detailed guides so you can quickly identify the root cause and apply the correct fix.

Investigate failing AI agent runs

To troubleshoot a failing AI agent run:

1. Reproduce the issue on the Test tab using a saved test case. This ensures your inputs are controlled and repeatable. Use expression mode to define complex data types like records, CDTs, and maps.
2. From the Monitor tab, collect context for reference: Request ID, AI agent version, inputs used, tools invoked, and timestamps.
3. Open the failing run and select the error to view details and category:
   • System Error: This is likely a platform or system object. Try again; if it persists, escalate to an administrator.
   • Tool Execution Error: This is a user-configured object (process model, rule). You can try to fix this.
4. Follow the link in the error details to the failing object (process instance, rule, query).
5. Apply the matching quick fix from below, then re-run with the same test case and confirm in the Monitor tab.
6. Validate the fix in the Test tab with the same saved case.
   1. Confirm step history and outputs.
   2. Save/rename the test case for future regression checks.
   3. In the Monitor tab, verify status, tool-call count, duration, and requester.
7. If it's fixed, keep the test case for regression. If not, escalate to an administrator and include the Request ID, AI agent version, failing object, timestamps, and screenshots.

Quick fixes

Use this table to quickly identify and resolve common issues. For more detailed guidance, see How to solve common issues with AI agents.

Symptom	Likely cause	Quick fix
Run fails immediately; permission message	Initiator lacks access to a required tool	Grant initiator access to all tools the AI agent may call; re-run.
Status shows "User Canceled"	You manually stopped the run	This is expected behavior when you click Stop. Review the steps completed before cancellation to identify issues. See Stop a running AI agent.
Status shows "System Canceled"	AI agent exceeded maximum tool calls (default: 30)	Review your AI agent's instructions and tool configuration to prevent excessive tool calls. See Run limitations.
Test fails with expression error	Invalid expression syntax in test input	Check the inline error message in the expression editor; confirm your expression is valid before running the test.
Early step throws null/type error	Missing or invalid inputs	Correct names/types; re-test with saved case.
Tool runs, then fails to format output	Output type mismatch	Align tool output to the configured output type.
Process tool shows node exception/timeout	Logic/timeout inside process model	Inspect instance vars; add error handling; avoid deep subprocess chains.
Parallel tool call fails	One or more parallel tool calls returned an error	Expand each tool call card in run history to see individual errors. Verify tools do not depend on each other. See Parallel tool call failures.
Expression evaluation error	Bad params or unsafe nulls in a rule	Unit-test rule with same inputs; add guards/defaults.
Record query empty/operator error	Unsupported operator or multi-record join attempt	Query one record type; use supported operators; move aggregations into a rule.
"Finds nothing" in document	Unsupported file, image-only PDF, too large/long	Use supported Appian docs with extractable text; mind size/page limits.
MCP tool card shows error icon	Tool removed or changed on MCP server	Reselect tools from the MCP server; remove unavailable tools. See MCP tool issues.
MCP tool fails at runtime	Server unavailable, auth failure, or rate limit	Check credentials in the MCP connected system; verify server availability; review vendor rate limits. See MCP tool issues.
Sub-agent fails with permission error	Initiator lacks access to the sub-agent or its tools	Grant the initiator access to both the sub-agent and all tools it uses; re-run. See AI agent tool permission errors.
Sub-agent times out after 60 minutes	Sub-agent execution exceeds the AI agent tool timeout	Simplify the sub-agent's task scope or break it into smaller, focused agents. See AI agent tool timeout errors.
Sub-agent fails but no error details appear	Error occurred more than two levels deep	Expand See Details on the failing tool call; test the sub-agent independently. See AI agent tool error depth limits.
One or more parallel tool calls fail while others succeed	Individual tool failure during parallel execution	Review error messages on the failed tool call cards; fix the underlying tool issue and re-run. See Partial failures in parallel tool calls.
Agent type mismatch error	Process agent used in agent chat component, or chat agent used in Execute AI Agent smart service	Use the correct deployment method for the agent type. Process agents run via the Execute AI Agent smart service; chat agents run via the agent chat component (a!agentChatField). See Agent types.

How to solve common issues with AI agents

This section provides detailed troubleshooting steps for specific types of failures. Each heading below represents a potential solution category that can help resolve different types of AI agent run failures.

Reproduce and collect context

• Reproduce in the Test tab with a saved test case; keep inputs stable across runs.
• Use expression mode to define test data for complex data types like records, CDTs, and maps. This allows you to create realistic test scenarios that reliably reproduce failing runs.
• From the Monitor tab, capture: Request ID, AI agent version, inputs used, tools invoked, timestamps.

Interpreting error details

• System Error (platform/system object): Retry once; if it persists, escalate with the items listed in When to escalate.
• Tool Execution Error (your objects): The failure is in a process model, rule, query, or document step. Follow the error link to fix.
• User Canceled: You manually stopped the AI agent run by clicking the Stop button. The AI agent stopped between steps, after any running tool completed.
• System Canceled: The AI agent run was automatically stopped because it reached the maximum number of tool calls (default: 30). This protects against runaway AI agents consuming excessive resources.

Jump to the failing object

• From the error panel, open the linked process model instance or expression rule.
• For process issues, drill into Process Activity to view node errors, PVs, and timing.

Access and security issues

• Symptom: The AI agent run fails immediately with a permission/access error.
• Fix: Ensure the initiator (or calling process) has access to every tool the AI agent may invoke. Re-run.
• Why it happens: Pre-execution checks block the run if any required tool is inaccessible.

Missing or invalid inputs

• Symptom: Early step error; nulls or wrong types.
• Fix: Verify required inputs and data types on the AI agent; correct names/defaults. Re-run with the same saved test case.

Output formatting and type mismatches

• Symptom: Tool executes, then fails when formatting to the configured output type.
• Fix: Align the tool's actual output structure with the AI agent's configured output type, or adjust the output definition accordingly. For list-based outputs, ensure the AI agent generates properly formatted data that can be parsed into the expected list structure.

Process model tool failures

• Symptom: Tool Execution Error; process instance shows node exceptions or timeouts.
• Fix:
  • Open the failing instance; inspect node inputs/outputs and PVs.
  • Implement proper error handling in your process models to prevent errors.
  • Add sensible defaults; shorten long waits.
  • Avoid deeply nested subprocess chains; surface errors earlier.
  • Important: The default tool execution timeout is 30 minutes. If a process model tool exceeds 30 minutes, the tool call fails.

Parallel tool call failures

• Symptom: One or more tool calls in a parallel batch fail while others succeed.
• Fix:
  • Open the run history and expand each tool call card. Failed parallel tool calls display individual error messages.
  • Identify whether the failure is specific to one tool or affects all parallel calls.
  • The AI agent evaluates results from all parallel calls—including failures—and determines its next action. If the AI agent cannot recover, it reports the error in its final response.
  • Verify that parallel tools do not depend on each other's output. If tools have dependencies, restructure them so the AI agent executes them sequentially.

Expression rule tool errors

• Symptom: Expression evaluation error, invalid parameters, unexpected nulls.
• Fix:
  • Open the rule from the error panel; unit-test with the same inputs used by the AI agent.
  • Add null guards and defaults; simplify complex expressions or split them into helper rules.

Record type query issues

• Symptom: Empty results or operator errors.
• Fix:
  • Each query targets one record type (no related record types).
  • Need aggregations (sum, avg)? Wrap them in an expression rule and call that as a tool.
  • Smart search is not supported for record query tools. Write your own smart search query using an expression rule tool.

Document and folder tool issues

• Symptom: AI agent "finds nothing" in a file; no explicit error.
• Fix:
  • The source must be an Appian document of a supported type.
  • Image-only PDFs (no embedded text) won't be read.
  • Full-document read supports PDFs up to ~20 pages; total size ≤ 100 MB; English content only.
  • Unsupported files are skipped (no error).
  • Guidance: The AI agent automatically chooses the document method (fact lookup vs whole-document reasoning vs extraction).

MCP tool issues

• Symptom: Cannot add tools from an MCP server at design time; the AI agent shows a connection error.
• Fix:
  • Verify the MCP server URL in the MCP connected system is correct and the server is running.
  • Check that the authentication credentials (API key or OAuth 2.0 Client Credentials) are valid and not expired.
  • Confirm network connectivity between Appian and the external MCP server.
• Symptom: An error icon appears on an MCP tool card in the AI agent.
• Fix:
  • The tool may have been removed or renamed on the MCP server. Open the tool configuration and reselect tools from the server.
  • If the tool no longer exists, remove it from the AI agent and choose a replacement.
• Symptom: MCP tool call fails at runtime with an error message from the server.
• Fix:
  • Review the error message in the tool output. Common causes include authentication failures, rate limiting by the vendor, or the server being temporarily unavailable.
  • For authentication errors, update the credentials in the MCP connected system.
  • For rate limiting, review the vendor's documentation and adjust your AI agent's behavior through its prompt (for example, add instructions to wait between calls or limit retries).

AI agent tool permission errors

• Symptom: The AI agent run fails when attempting to invoke a sub-agent using the AI agent tool. A permission or access error appears.
• Fix: The initiator of the main AI agent must have access to both the sub-agent and all tools the sub-agent uses. Grant the initiator the required permissions, then re-run.
• Why it happens: The AI agent tool invokes the sub-agent as the initiator of the main AI agent. Pre-execution checks block the call if the initiator lacks access to the sub-agent or any tool the sub-agent may call.

AI agent tool timeout errors

• Symptom: The AI agent tool call fails after a long execution time. The error indicates the sub-agent exceeded its timeout.
• Fix:
  • Reduce the sub-agent's task scope. A sub-agent that invokes many tools or processes large data sets can exceed the 60-minute AI agent tool timeout.
  • Break complex tasks into smaller, focused sub-agents that complete faster.
  • Test the sub-agent independently in the Test tab to measure its execution time before adding it as a tool.
• Why it happens: The AI agent tool has a 60-minute execution timeout. If the sub-agent does not complete within that window, the tool call fails and the main AI agent receives an error.

AI agent tool error depth limits

• Symptom: A sub-agent fails, but the main AI agent's error panel shows limited or no details about the root cause.
• Fix:
  • Expand See Details on the failing AI agent tool call in the Test or Monitor tab. The expanded view shows Tool UUID, Reasoning, Input, and Output.
  • Test the sub-agent independently to reproduce and diagnose the error with full visibility.
  • If the sub-agent calls another sub-agent (three levels deep), errors from the deepest level are not surfaced. Test each agent in the chain individually.
• Why it happens: The AI agent tool surfaces errors up to two levels deep. Errors that occur at the third level or deeper are not propagated to the main AI agent's error display. The AI agent tool supports synchronous calls only and does not support parallel execution of multiple sub-agents.

Partial failures in parallel tool calls

• Symptom: One or more tool calls in a parallel step fail while others succeed. The AI agent continues running but may produce incomplete results.
• Fix:
  • In the Test or Monitor tab, expand the parallel step to view individual tool call cards.
  • Click the error status on the failed tool call card to view the specific error message.
  • Identify the root cause (timeout, permission error, invalid input) and fix the underlying tool issue.
  • Re-run the AI agent with the same test case to confirm the fix.
• Why it happens: During parallel execution, individual tool failures do not block the entire step. Successful tool calls complete normally. The system sends error messages for failed calls alongside successful results to the AI model, which determines the next action. The AI agent may proceed with partial data or attempt a recovery strategy based on its instructions.

When to escalate

Escalate only if the error persists after a retry. Include the following details:

• Request ID, failing object/tool, timestamps
• Screenshot of the error panel
• A brief summary of what you already tried

Best practices

The best way to avoid troubleshooting is to design your AI agents with reliability in mind from the start. These practices help prevent common issues and make debugging easier when problems do occur.

• Start with a minimal AI agent that performs a simple intake or triage task, then add tools and complexity gradually.
• Name your inputs clearly and avoid creating multiple tools that do the same thing. This helps the AI agent select the correct tool unambiguously.
• When calling an AI agent from a process model, use the Execute AI agent smart service to pass structured data and capture outputs for easier downstream debugging.

See the Best Practices for Designing AI agents for more helpful tips. For testing guidance, see Monitor AI agents.

Feedback