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. If the credentials are in the team namespace, confirm that the current account is still the creator or member of the team; the team credentials will no longer be parsed after exiting the team.
  4. Confirm that the workflow uses the correct Provider identifier or selected credential ID, not the display-only label. Then reopen the editor to refresh the credential list.

Third-party service authorization cannot be connected

How to fix:

  1. First, look at the prompts when saving authorization: if it prompts that the credentials are invalid, go back to the upstream backend to regenerate the token; if it prompts that the permissions are insufficient, add the corresponding permissions to the token.
  2. If the verification passes but the account displayed is not the one you want, it means that the credentials belong to another account or sub-application. Change the credentials of the target account and save again.
  3. If it fails when running and normal when saving, it is probably because the token has been revoked or expired by the upstream; go back to "Integration → Third-Party Authorization" to update the value of this authorization.
  4. If a colleague runs your workflow and it reports a missing authorization, that is because it is bound to your personal authorization; switch to a team authorization, or have them create one of their own.

View full description of third-party authorizations

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
workflow:
  - step: call_llm
    agent: writer
    input: "生成摘要"
    retry:
      max_attempts: 3
      backoff: exponential
      initial_delay: 2000
      max_delay: 30000
  1. If you hit rate_limit often, upgrading your Provider account Tier with BYOK is the fundamental fix.
  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 a stronger model — which one exactly depends on the list your provider account currently offers.

Code Step Reports Permission Denied or Network Error

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

  • The file system is mostly read-only — what you can write to is this run's artifact directory and the temporary directory;
  • The network can only go out but not in (cannot monitor the port);
  • CPU/memory/runtime are capped.

How to fix:A permission denied usually means writing outside the artifact directory — read this run's artifact directory from os.environ["BRAIDRUN_OUTPUT_DIR"] and write inside it instead of hard-coding an absolute path (a hard-coded path makes agent steps and code steps disagree about the directory). A network error is usually a host that is not on the egress allowlist; check with your administrator.

"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. Check whether the status bar shows that other collaborators hold edit locks. The lock holder will actively release it when exiting the editor; by default, it will wait up to 5 minutes to expire when exiting abnormally.
  3. There is currently no team administrator who forcibly unlocks the entrance; after the lock expires, collaborators with editing permissions will reopen the editor to obtain it.
  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. Confirm that the deployment administrator has enabled approval email notifications and configured the email service correctly; the approval record itself will not be lost when the notification is turned off.
  2. approvers fills in the user ID, not the email or display name; after configuration, only users on the list can decide to approve.
  3. When approvers is empty, the notification falls back to the execution initiator; decision-making permissions also allow collaborators with execution permissions for the workflow to operate.
  4. Even if you do not receive the email, you can directly open the approval list to view the pending approval items that the current account has the authority to process.

I Approved but the Workflow Didn't Continue

After the approval decision is submitted, the execution will re-enter the runnable process. If the page status has not changed for a long time:

  1. Refresh the execution details page. Is it already RUNNING?
  2. Check whether the approval is still PENDING and whether the execution has FAILED, CANCELLED, INTERRUPTED or TIMED_OUT.
  3. Record the approval ID and execution ID, and submit for troubleshooting through the currently deployed support channel.

I still can’t see a workflow after joining the team

Joining a team does not automatically gain access to all workflows created by members of that team. Please ask the workflow owner to select the TEAM or SHARED scope in the sharing settings and check that your account has been granted view permissions.

A Colleague Can’t Edit a Workflow

The team identity itself does not distinguish between Viewer/Editor. Please have the workflow owner turn on the sharing permissions and confirm that the colleague has canView and canEdit; if you still need to run, share or delete, grant canExecute, canShare or canDelete respectively.

How to hand over the workflow to colleagues for continued maintenance?

There is currently no workflow ownership transfer operation. You can grant editing and execution permissions to colleagues; if you need to form an independent copy, you can export the workflow, and then your colleagues can import it to their own account. Credentials are not exported with the workflow and require reconfiguration by the recipient.

Pay/Bill

Credit Card Charge Failed

  1. First check the failure reason given on the bill or settlement page, and then follow the entry provided on the page to try again or change the currently available payment method.
  2. Plan status, retry count, and grace period depend on the payment channel and subscription configuration. Do not infer a fixed number of days.

The billing or invoice information is incorrect

First check whether the account settings provide a modification or download entrance; how to correct the generated documents shall be subject to the page prompts, order agreement or sales team confirmation results.

Tried Everything but Still Doesn't Work

  1. Record workflow ID, execution ID, occurrence time, error code and reproducible steps; do not attach API Key, password or complete credentials when submitting.
  2. Contact the administrator or support team through the support portal provided by the current deployment; Enterprise users should handle it according to the support channel agreed in the contract.

Last Updated · 2026-08-06

Was this page helpful?