AutoMerge is generally available

Last updated:

Run Fails with Guardrail Failure

Understanding and fixing guardrail violations in automation runs.

When a run status shows "guardrail_failure", Agent0 violated one or more guardrail constraints you configured. This is by design to ensure automations behave safely.

Required Tool Calls Not Met

The most common guardrail failure: Agent0 didn't call tools you marked as required.

Why this happens:

  • Agent0 wrote a summary but didn't take the required action
  • Prompt wasn't explicit enough about what to do
  • Tool isn't available because its integration is not connected, or its call fails with invalid parameters

How to fix:

  1. Check which tools were missing:

    • Open the failed run
    • Look at tool calls that were made
    • Compare to the tools marked Required in Tools & Skills → Configure tools
  2. Make the prompt more explicit:

    Query error rate for service {{label.service}}.
    
    Post your findings to #incidents. This is required.
  3. Verify tool is accessible:

    • Required tools are force-included even when an allowlist would exclude them. Check the tool's integration access and errors rather than adding it to a separate allowlist.
    • For Slack: Verify Slack integration is connected
    • For GitHub: Verify GitHub integration is connected
  4. Test again:

    • Use Test button with realistic variables
    • Verify the required tool gets called
    • Adjust prompt if needed
Tip

Agent0 gets one automatic retry when required tools are missing. If it still doesn't call them after the retry, the run fails with guardrail_failure.

Timeout Exceeded

Automation ran longer than the configured timeout.

Why this happens:

  • Complex queries over large time ranges
  • Too many services to analyze
  • External API calls taking too long
  • Infinite loops in conditional logic

How to fix:

  1. Increase timeout:

    • Go to Guardrails > Timeout
    • Set a higher value (e.g., from 10m to 20m)
    • Consider if the automation really needs that long
  2. Simplify the prompt:

    • Reduce time ranges for queries
    • Limit number of services to analyze
    • Break complex tasks into separate automations
  3. Check for runaway logic:

    • Review prompt for open-ended instructions like "keep querying until..."
    • Add specific limits: "Query top 5 services" not "Query all services"

Tool Parameter Overrides Blocking Execution

Tool parameter overrides can inadvertently prevent tool calls from succeeding.

Why this happens:

  • Overridden parameter is invalid (wrong channel ID, malformed timeframe)
  • Override uses a variable that's empty for this trigger type
  • Parameter name is misspelled (silently dropped)

How to fix:

  1. Review tool parameter overrides:

    • Open Tools & Skills → Configure tools, select the tool, and review Parameter overrides
    • Check each override is still valid
    • Verify parameter names match tool schema exactly
  2. Check variable values:

    • If override uses {{variable}}, ensure that variable is populated for your trigger type
    • Example: {{slack.channel.id}} is empty for schedule triggers
  3. Test without overrides:

    • Temporarily remove overrides
    • Test to see if automation succeeds
    • Add back overrides one at a time to find the problematic one

Network Level Blocking Tool

Network level restrictions can prevent sandbox-native operations from running.

Why this happens:

  • No Network blocks sandbox operations (git/gh CLI, curl, webhooks)
  • Tool needs network access but you have No Network set

How to fix:

  1. Check which operations need network access:

    • Connector tools work under any setting: Slack, GitHub API, Linear, Dash0 query tools all work with No Network
    • Sandbox operations need access to their destination hosts: Trusted hosts only permits listed hosts, including GitHub
  2. Update network level only if needed:

    • Go to Guardrails > Network Access
    • Use Trusted hosts only for listed destinations, or Full Network when the destination is not listed
    • Save and test again
Note

Connector tools do not need Full Network. Sandbox commands such as gh can reach GitHub with Trusted hosts only, but write operations still require repository write access.

Credit Budget Exceeded

The automation's rolling credit budget was used up before the run started, so the run is blocked with a Guardrail Failure.

Automations overview showing failed runs with a credit budget exceeded tooltip

Why this happens:

  • The automation ran more often than expected within its rolling window (webhook floods, noisy triggers, retries)
  • Individual runs cost more credits than expected (long prompts, many tool calls)
  • The Credit Budget configured in guardrails is too low for actual usage

How to fix:

  1. Check the failure tooltip:

    • Hover the GUARDRAIL FAILURE badge on the run in the automation's overview or Runs tab
    • It shows the configured budget and the amount spent in the rolling window, for example: Credit budget of 1 exceeded (8.91 spent in the last 30d)
  2. Review recent spend:

    • Check Total credits used and Avg credits per run in the automation's overview
    • Identify whether one trigger type or a small number of runs is driving spend
  3. Adjust the budget or the trigger:

    • Go to Guardrails > Credit Budget and raise the budget or widen the window if the current usage is expected
    • If usage is unexpected, fix the trigger (debounce, concurrency) or the prompt (fewer tool calls, tighter scope) instead of just raising the budget
Note

Active runs are not canceled when the budget is hit. Concurrent runs can pass the check before their costs are recorded, so spend can exceed the budget by the costs of multiple in-flight runs.

Required Tool Unavailable

Required tools are included even when Allowed Tools would otherwise exclude them. A required tool still needs to be available to the run, and its calls can fail because of missing integration access or invalid parameters.

Check the tool name in Required Tool Calls, the integration connection, and the run's tool errors. Adding a tool to Required Tool Calls does not guarantee that its operation succeeds.

Debugging Guardrail Failures

Systematic approach to identify which guardrail failed:

  1. Check run status message:

    • Opens the failed run
    • Look for specific error message
    • Usually says which guardrail was violated
  2. Review tool calls:

    • See which tools were actually called
    • Compare to required tool calls list
    • Identify what's missing
  3. Check run duration:

    • If runtime equals your timeout, timeout was exceeded
    • Otherwise, issue is likely required tools or tool access
  4. Test in isolation:

    • Create a minimal test automation with same guardrails
    • Simplify prompt to just call one required tool
    • If that works, the issue is in your complex prompt logic

Further Reading