Skip to main content

Troubleshooting Workflows

At a glance​

This guide covers common Workflow Builder issues: execution failures, block errors, timeouts, variable problems, and scheduling issues.

Execution failures​

The workflow fails immediately​

Possible causes:

  • A start block is missing
  • A block configuration is incomplete
  • A referenced variable does not exist

Solutions:

  1. Verify that the workflow has a Start block or a Trigger (webhook, schedule, event).
  2. Open the debug panel and check the error message of the first failed block.
  3. Verify that all variables used are defined (see the Variables section below).

The workflow gets stuck (timeout)​

Possible causes:

  • An external call block is not responding
  • An infinite loop in a Loop block
  • The execution time exceeds the limit

Solutions:

  1. Check the timeouts configured on integration and API call blocks.
  2. Check the exit condition of the Loop block — add a maximum iteration limit.
  3. Review the maximum duration in Limits and quotas.

The workflow fails in Run mode but works in Test mode​

Cause: The two modes use different execution paths. Test mode is synchronous, Run mode is durable with checkpointing.

Solutions:

  1. Verify that external call blocks are idempotent (can be re-executed without side effects).
  2. Check the execution logs in Run mode in the Executions panel.
  3. Check environment variables — they may differ between the two modes.

Block errors​

Condition block: unexpected branch​

Cause: The condition is evaluated differently than expected.

Solutions:

  1. Check the type of the compared variable (text vs number).
  2. Use debug mode to inspect the actual value of the variable at the time of evaluation.
  3. Be aware of string comparisons: "10" (text) is different from 10 (number).

Tool block: "Tool not found"​

Possible causes:

  • The referenced tool has been deleted or renamed
  • The tool is not available in the workspace

Solutions:

  1. Verify that the tool exists in Agent Studio > Tools.
  2. Reconfigure the block by selecting the tool again.

Email block: "Send failed"​

Possible causes:

  • Invalid email address
  • Malformed email template
  • Sending quota exceeded

Solutions:

  1. Check the recipient email address.
  2. Test the template with static values before using variables.
  3. Review the sending quotas in the workspace settings.

Variables and resolution​

Unresolved variable​

Symptom: The block displays the raw variable (e.g., {{variableName}}) instead of its value.

Possible causes:

  • Incorrect variable name (case, hyphens, spaces)
  • The variable is defined in a block that has not yet been executed
  • The variable's source block is on another branch of the workflow

Solutions:

  1. Check the exact spelling of the variable, including case.
  2. Verify that the block defining the variable is upstream in the execution flow.
  3. Use the variables panel to see all available variables at a given point in the workflow.

Empty variable​

Cause: The source block produced an empty or null result.

Solutions:

  1. Inspect the source block output in debug mode.
  2. Add a default value with the syntax {{variable || "default value"}}.

Scheduling​

The schedule does not trigger​

Possible causes:

  • The workflow is not activated
  • The cron expression is invalid
  • The timezone is incorrect

Solutions:

  1. Verify that the workflow is in Active status (not paused).
  2. Validate the cron expression — use an online tool to check the next execution.
  3. Check the timezone configured in the schedule settings.

Unwanted multiple executions​

Cause: The schedule triggers the workflow more often than expected.

Solutions:

  1. Check the cron expression (e.g., * * * * * = every minute, not every hour).
  2. Verify that there are not multiple triggers on the same workflow.

See also​

Need help?​

Contact us: Support and contact.