TroubleshootingCopy Anchor Link

Diagnose from the narrowest shared failure to the outer transport. This order prevents configuration and capability problems from being mistaken for model or network failures.

Safe diagnostic orderCopy Anchor Link

1. Reproduce in Action Agent Studio chat. Action Agent Studio can run while the Agent is passive. If Action Agent Studio also fails, inspect the saved model, credentials, credits, and capabilities before investigating an external route.
2. Confirm scope and lifecycle. Check the exact organizationId, actionAgentId, and sessionId. Confirm whether the operation creates a session, continues one, or ingests a trigger.
3. Check readiness. Confirm the Agent is active for external execution, the model selection is complete, required provider credentials or platform credits are available, and any attached binding or connection is ready.
4. Check one capability at a time. Test Knowledge without tools, then named HTTP, then MCP. Disable unrelated capabilities while isolating a failure.
5. Check transport state. For a session failure, verify the Agent/organization/session triple. For a stream failure, resume the existing stream instead of sending the message again.
6. Inspect sanitized runtime evidence. Use Agent logs and stable UI error codes. Redact IDs if your support process requires it, and never include secret-bearing values.

Passive or inactive AgentCopy Anchor Link

Symptom: Action Agent Studio chat works, but a REST, SDK, hosted MCP, channel, or scheduled start is rejected or ignored.

1. Confirm active: true for the Agent in the same organization.
2. Remember that draft and passive Agents both store active: false.
3. Confirm the organization has not reached its active-Agent allowance. Activation can fail even when configuration looks complete.
4. Test a saved turn in Action Agent Studio before activating again.

Action Agent Studio is the only source that can start a new session while the Agent is passive. Deactivation also blocks new trigger ingress, but it does not revoke an existing public sessionId. See Action Agent lifecycle.

Trigger event is accepted but no Agent turn runsCopy Anchor Link

A successful vendor response does not prove that an Agent ran. Slack, Discord, and Teams commonly return 200 { "ok": true } after ignoring a bot message, missing workspace connection, inactive binding, disabled event, scope mismatch, or a caught processing error.

Check these conditions in order:

1. The Agent is active and belongs to the routed organization.
2. Exactly one binding exists for that Agent and channel, and its status is active, not needs_config.
3. The inbound event is enabled and maps to the expected event name. An empty events array is a runtime wildcard for otherwise eligible channel events, so save at least one intended event name.
4. The event matches the saved channel scope.
5. The organization connection or integration credential can still authenticate.
6. The turn can obtain model configuration, provider credentials, platform credits when applicable, and required tool connections.

For Slack, Discord, and Teams, the event's workspace or tenant must resolve through the platform integration to an organization OAuth connection saved on the binding. The current platform ingress handlers do not route events to a binding that has only an integrationCredentialId; use an OAuth connection for these channels.

For email, use the exact URL generated by Action Agent Studio, including both actionAgentId and organizationId. A missing email query ID is rejected before authentication and before the trigger limiter, and returns 400. After that check, an invalid email secret or HMAC returns 401; invalid JSON returns 400.

Slack, Discord, and Teams use vendor authentication rather than the email binding secret. A 401 there usually means the Slack signature, Discord Ed25519 signature, or Teams Bot Framework authorization did not validate. A 429 can come from the 10-per-10-second trigger window or the broader API per-IP limiter.

Do not copy the email secret from an old binding into a new one. Saving an email binding creates a per-binding secret, and Action Agent Studio reveals it only when it is first generated. See Triggers.

Scheduled trigger does not runCopy Anchor Link

1. Confirm the Agent and scheduled binding are active.
2. Confirm a positive interval, valid time/timezone fields, and a non-empty prompt are saved.
3. Remember that the scheduler checks once per minute. It advances from the current claim time and does not backfill every missed interval.
4. Compare nextRunAt with the expected timezone conversion. Each due tick creates a new scheduled session and uses the silent reply policy.

If starting or sending a claimed scheduled run fails, ActionFlows restores the prior nextRunAt so the binding can be retried on a later scheduler pass.

Knowledge search returns no resultsCopy Anchor Link

1. Confirm the collection belongs to the same organization as the Agent.
2. Confirm the collection is still attached and not deleted.
3. Open the collection and check each document's extraction status:
   • pending: extraction has not completed.
   • ready: extracted text is stored. A ready document can still contain the marker no text extracted when no text could be extracted.
   • failed: the latest extraction attempt failed. Any older extractedText is not cleared, so stale content can remain searchable.
4. Search for a distinctive term from the document body. Current search also matches the file name when full-text extraction has no match.
5. If search returns a document, call read_document with its documentId. A successful search is not a guarantee that the document has useful extracted text.

Search returns at most 8 hits, and each read returns at most 4,000 characters. Read later offsets when more content is needed. The current search query does not explicitly filter on extractStatus; a pending document normally has no extracted text, while a failed document can still expose stale extracted text from an earlier successful run. The no-text marker is stored as ready content. See Knowledge.

The model ignores tools or reports unsupported tool callsCopy Anchor Link

1. Save the tool configuration, then start a new message so the runtime reloads it.
2. For BYOK, select an enabled model whose catalog metadata includes functionCalling.
3. For a platform model, verify that the specific platform model supports tool use. The current platform picker filters chat model types, not a functionCalling capability field.
4. Confirm the named tool has a non-empty name and an HTTP(S) URL template. Its description and parameter schema affect what the model sees, but are not part of the current readiness check.
5. For named HTTP tools, verify required parameters and {placeholders} in the URL template.
6. For httpRequest, use an HTTP or HTTPS URL. URLs with embedded credentials, private addresses, and unsafe redirects are blocked.
7. Test the capability in Action Agent Studio and inspect the tool call state. The model chooses whether to call a tool; attaching one does not force a call.

There is no automatic fallback from an unsupported or unavailable selected model. Select a compatible model explicitly. See Tools and Model selection.

Named HTTP tool failsCopy Anchor Link

Check the tool output in Action Agent Studio without copying authorization data into the issue. Save/update validation and runtime httpRequest failures use different messages.

Save/update validation:

• INVALID_URL: the saved template is malformed or uses a non-HTTP(S) scheme.
• UNSAFE_URL: the saved template's sample URL contains embedded URL credentials or resolves to a private, loopback, link-local, reserved, or otherwise blocked address. This is a save validation code, not the runtime text below.

Named-tool execution:

• Missing required parameter: the model omitted a required declared parameter.
• Missing path parameter: a {name} placeholder had no input value.
• Unsupported HTTP method: stored outside DELETE, GET, HEAD, OPTIONS, PATCH, POST, or PUT.
• Runtime URL failures are returned as messages such as URL must use HTTP or HTTPS protocol, URL must not include credentials, Blocked unsafe remote URL: ..., or Too many redirects while fetching ....
• Timeout or response-size error: the call exceeded 1-300 seconds or the response exceeded 5 MiB.
• HTTP error status: the remote API returned a non-2xx response. The tool reports the HTTP status in its error, but check whether the response body is safe to retain in a transcript.

Static named-tool headers are currently stored in headersJson rather than encrypted. Authentication payloads are encrypted, but do not put reusable secrets in static headers unless you accept that current storage behavior.

MCP server is missing or disconnectedCopy Anchor Link

In the MCP panel, inspect each connection's stable status and lastError code:

A failing MCP server does not fail the whole turn. Its tools are omitted while other tools can continue. Probe refreshes the displayed catalog; the runtime only exposes names in enabledToolNames, and an empty list means no tools, not all tools. Save an Agent MCP change or let the session suspend and resume to force runtime reconnection. See MCP.

Session not found or not readyCopy Anchor Link

NOT_FOUND means no open session matches all of:

• the requested sessionId;
• the requested actionAgentId; and
• the authenticated or supplied organizationId.

A closed, deleted, or foreign session fails instead of opening another conversation. Do not substitute externalId for sessionId.

AGENT_SESSION_NOT_READY means the session row exists but its Trigger chat binding did not appear within the 120-second cold-start wait. Check queue/runtime availability and retry the same send later. Do not create repeated sessions while diagnosing one queued start. If the CMS concurrent-run limit is 0, the organization cannot admit any new Agent run; queueing does not bypass that setting.

Every REST, SDK, or hosted MCP start call creates a new session. endUserId does not look up or reopen an existing public session. See Sessions & chat.

Stream interrupts or returns an empty resultCopy Anchor Link

1. Keep the same Agent, organization, and session IDs.
2. Do not send the user message again solely because delivery disconnected; the original turn may already be completing or persisted.
3. Reconnect with GET /api/action-agents/{actionAgentId}/sessions/{sessionId}/stream?organizationId={organizationId}.
4. Use Last-Event-ID only if the client captured a cursor. The current public encoder does not emit id: fields; otherwise omit both cursor inputs so the server uses the persisted session cursor.
5. Treat an SSE error event as the end of public delivery. Provider details are intentionally replaced with An error occurred..

If reconnect finds no resumable live stream, the route emits a done event with an empty text field. See Sessions & chat.

Generated artifact is missingCopy Anchor Link

1. Confirm the turn reached completion. Artifact persistence is a turn-completion side effect.
2. Confirm the assistant output contains a recognized file part or file-shaped tool result. Ordinary text and ordinary JSON tool results are ignored. A string field named data can be collected but is not resolved by the current Agent artifact path.
3. Confirm the payload reaches the resolver as a non-empty buffer, supported URL/data-URI/base64 form, or supported byte-array/Buffer form of at most 25 MiB.
4. For a remote URL, confirm it is HTTP(S), has no embedded credentials, passes DNS and redirect SSRF checks, and returns a successful response.
5. Inspect Agent/runtime logs for Agent artifact exceeds size limit or Failed to persist agent generated artifact without copying the payload or its signed URL.

Artifact persistence failures are logged and do not fail the chat turn. A missing artifact therefore does not imply a missing text reply. See Artifacts.

RelatedCopy Anchor Link

• Action Agent lifecycle
• Limits
• Triggers
• Tools
• Knowledge
• MCP
• Artifacts