Skip to main content
This guide covers the most common operator issues in AgentRuntime. Start from Command Center for run-level triage, then use the sections below by symptom.

​
Failed runs

​
Find the error

  1. Open Command Center → Failed recently (last 24 hours)
  2. Click Open run to view the event log in Workflow Studio
  3. Find the first step with Failed status and read the error message
  4. Check other steps on the canvas — Cancelled and Skipped (Blocked) are expected on fail-fast runs (not bugs)

​
Step status on failed runs

When one step fails, the run is terminal failed. Other steps are labeled explicitly: If the Events panel still shows “Processing…” on a Cancelled step after a refresh, reload the run — the event log should include a step_cancelled event. See Runs and Command Center.

​
Failure codes

​
Retry after fixing

Failed runs are terminal. After fixing the root cause:
  1. Publish a new workflow version if the graph changed
  2. Start a new run — do not expect the old run to resume
Cancelled and Skipped (Blocked) steps on the old run are historical — they record what happened on that attempt. A new run executes the graph from the beginning (or from a future checkpoint API when shipped). For transient API errors, add retry_count on flaky steps. See Workflow patterns. Planned continue-from-failure (checkpoint retry, same-run retry) is documented in Run recovery (roadmap) — not available yet.

​
Run appears stuck

A run waiting on human approval is working as designed, not stuck.

​
MCP binding errors

Symptoms: MCP_TOOL_FAILED on the first tool step, validation errors mentioning bindings, or “instance not resolved” in dry-run.
1

Validate the instance

Go to MCP, open Instance config for the instance, confirm the connection is wired and the profile is active. Optionally run MCP validation at /mcp/{server_id}/validate.
2

Check the connection

Confirm the bound connection exists and credentials are current. OAuth connections showing Reconnect need re-authorization.
3

Dry-run validate

In Workflow Studio, click Validate to surface binding errors before running.

​
Per-connector guides

​
Credit exhaustion

Symptoms: INSUFFICIENT_CREDITS failure code, runs fail to start, billing warnings in Console.
1

Check balance

Go to Settings → Billing → Usage or GET /v1/billing/usage.
2

Identify spend

Review Analytics credits consumed and usage history for heavy workflows.
3

Add credits

PAYG top-up from Billing, or upgrade plan if included credits are insufficient.
Credit spend order: trial → included → PAYG. See Billing and credits.

​
OAuth reconnect

Symptoms: Reconnect banner on a connection, 401/403 from Google or LinkedIn MCP tools, token refresh failures.
1

Reconnect

On Connections, open the Google account card (or the relevant provider) and Reconnect / re-authorize.
2

Re-validate MCP instances

Validate all instances bound to that connection.
3

Check admin policy

For Google Workspace, confirm your admin allows third-party app access and required scopes.
Rotating credentials does not retroactively fix failed runs — start new runs after reconnect.

​
API 401 and 403 errors

​
401 Unauthorized

​
403 Forbidden

See API authentication and Roles and permissions.

​
Validation errors (422)

Dry-run validation (POST /v1/workflows/{id}/validate) catches issues before execution:

​
Template fields look wrong after editing

See Feature availability for preview vs GA features.

​
Memory errors (preview)

​
Still blocked?

  1. Gather: workflow ID, run ID, failure code, step ID, timestamp
  2. Check Command Center and the run event log
  3. Email support@agentruntime.io with the details