Skip to main content
DocsReferenceTroubleshooting

Troubleshooting

A guide to common symptoms: failed workflow runs, save errors, missed schedules, and missing approval notifications.

Organized by "Symptoms You See." Quickly locate the nearest one and follow "How to Repair". If it can't be fixed, go to "FAQ" or submit a work order.

The Execution Keeps Pending and Remains RUNNING.

Check first:

  1. Check the top of Execution History for a concurrency-limit-reached notice. Free is 1 concurrent, Pro 5, Team 15—has your number of simultaneous runs hit the limit?
  2. Check whether the manual_approval step of this workflow is stuck at the front.
  3. Let it wait for another 30 seconds - an occasional instant. The work order is PENDING after more than 2 minutes.

Execution Failed: credential_not_found

How to fix:

  1. Look at the credential name prompted in error_message.
  2. Open Credential Center - Does a credential by this name really exist? Capitalization, underscores/dashes must be consistent.
  3. Have you created credentials in the "Team Namespace" but you are currently in the Viewer role? Viewer cannot reference credentials.
  4. There is something on the list but it has not been parsed - log out and log in again to refresh the permissions.

Execution Failed: rate_limit_exceeded

Reason:Your or the platform's LLM Provider current limit is triggered.

How to fix:

  1. Add retry strategy to the failed step:
yaml
- id: call_llm
  type: single
  agent: writer
  retry:
    max_attempts: 3
    backoff: exponential
    initial_delay_ms: 2000
    retry_on: [rate_limit, http_5xx]
  1. If you often rate_limit, BYOK upgrading Provider account Tier is the fundamental solution.
  2. When running many tasks in batch, use sub_workflow + max_parallel to control concurrency.

Execution Failed: Timeout

Reason:A single step exceeds its timeout value, or the entire execution exceeds the workflow-level timeout.

How to fix:

  • code step: add an explicit timeout field on the step (in seconds, default 30).
  • LLM step: It may be that the model generation is too long; reduce max_tokens or use a faster model.
  • The entire workflow is slow: add a timeout field at the top (in seconds, default 3600).

Agent Output Is Empty or Invalid

Check first:

  1. Execution details → Click this step → Look at "Agent tool_call history" to see if you were directed to the wrong tool.
  2. Check if the input variable is empty - is the upstream step skipped by the condition?
  3. Adjust temperature: 0–0.3 for reasoning/classification tasks; 0.6–0.9 for creativity.
  4. task description plus more specific few-shot examples.
  5. Try changing to a stronger model (claude-opus-4-7 / gpt-5).

Code Step Reports Permission Denied or Network Error

The code step runs in an isolation sandbox, with restrictions:

  • The file system is read-only - only /tmp is writable;
  • The network can only go out but not in (cannot monitor the port);
  • CPU/memory/runtime are capped.

How to fix:permission denied usually means you are trying to write to a path other than /tmp - /tmp/something instead. Most of the network errors are caused by the sandbox blocking your target host (the platform has an egress whitelist). You can submit a work order to add the whitelist.

"YAML Is Inconsistent with DAG" Prompt When Saving

It means that the round-trip rule is not satisfied after you manually changed the YAML. Common reasons:

  • Used camelCase field name (should be snake_case)
  • References a deleted preset or agent
  • depends_on points to a step id that does not exist

Clicking the "Verify" button will give you the exact line number - fix it according to the error location.

The Editor Cannot Be Opened / Keeps Spinning in Circles

  1. Refresh it. Usually transient.
  2. Look at the status bar showing "xxx is editing" - someone else holds the edit lock. It will automatically release after 5 minutes of no operation, or contact the other party.
  3. Admin can "force unlock" in team settings.
  4. Clear browser cache/change browser to test.

The AI Assistant Diff Failed Validation After It Was Applied

Ctrl / Cmd + Z to undo—the editor supports multi-level undo. Then paste the error message plus the original YAML back to the assistant and it'll fix it.

cron It Didn’t Trigger on Schedule

  1. Is the "next trigger time" on the schedule details page consistent with expectations? Time zone mismatch is the most common cause.
  2. Is there any record of "Last 10 Trigger History"? If not, it may be that the workflow has been archived or deleted.
  3. Look at the status of the workflow - is it paused? The pause schedule still counts, but will not actually trigger.
  4. Manually verifying the workflow itself with the "Trigger Once Now" button is fine.

Webhook Trigger Returns 401 / 403

  1. API Key method: is the key in the Authorization: Bearer or X-API-Key header correct? Has the key expired, and does it have the WEBHOOK_TRIGGER scope?
  2. HMAC 兼容方式：你是否用 HMAC-SHA256 对 raw body 算了签名，放 X-Webhook-Signature 头？格式是 sha256=<hex>。注意：绑定了 API Key 的 webhook 不再接受 HMAC 签名。
  3. Is the webhook ID in the URL path correct? Was the corresponding workflow deleted?

Webhook Trigger 200 but Execution Does Not Start

200 only means "request accepted", execution may be rejected:

  • Whether workflow is paused;
  • Whether this package reaches the concurrency/scheduling quota;
  • Verification failed when body was mapped to variables (required fields are missing/type is wrong).

Webhook trigger log - In the "History" tab of the scheduling details page, you can see the details of the platform's analysis after receiving the request.

manual_approval Never Push Notifications

  1. Is the "Notification Configuration" page bound to any channel of Slack / Feishu / Email?
  2. Audit log → Filter approval_notify_failed - See why the notification cannot be sent (webhook url invalid? Email bounce?).
  3. When the approvers list is empty, it will notify "all Admin and above" by default - is your account one of them?

I Approved but the Workflow Didn't Continue

Post-approval workflow should continue within 10 seconds. Did not continue for more than 1 minute:

  1. Refresh the execution details page. Is it already RUNNING?
  2. The system is busy and may be queued for 30 seconds - etc.
  3. Raise a work order after more than 5 minutes.

Can't See Workflow After Switching Teams

Workflows are isolated by team - they are not displayed across teams. Make sure you have selected the correct team (pull down in the upper right corner). If you switch from "Individual" to "Team", you need to re-create the workflow in the team or move from individual.

A Colleague Can’t Edit a Workflow

Is he a Viewer in this team? Viewer is read only. Just upgrade him from Admin to Editor.

I'm Not the Owner, but I Want to Transfer the Workflow I Created

"Move to Team" requires you to be Editor or above in the target team. Just join the target team yourself.

Pay/Bill

Credit Card Charge Failed

  1. Billing page → "Retry Debit". After 3 failures, the package will be temporarily downgraded to Free - it will be automatically restored as long as you successfully deduct money within 14 days.
  2. Chinese cards may be risk controlled by Stripe, please use Alipay/WeChat Pay.

The Invoice Title Is Wrong

You can change the invoice details on the Billing page before the next month's invoice is issued. Invoices already issued require an email to billing@braidrun.com to void and reissue.

Tried Everything but Still Doesn't Work

  1. "Help" in the lower right corner → Submit a work order. Automatically attach browser context + most recent execution ID.
  2. Enterprise Plan → Contact dedicated CSM directly.