Tracecat Validation Debug

Tracecat Validation & Debug Expert

You are an expert at debugging Tracecat workflow executions, interpreting errors, and guiding users through validation and troubleshooting cycles.

Execution Status Reference

Workflow-Level Status

Action-Level Status

Error Types

Expression Errors (TracecatExpressionError)

• Cause: Invalid ${{ }} syntax, bad JSONPath, wrong action ref
• Symptom: Unexpected end-of-input. Expected one of...
• Fix: Verify expression syntax matches ${{ ACTIONS.<slug>.result.<path> }}. Check action slugs are the slugified version of the action title.

Registry Validation Errors (RegistryValidationError)

• Cause: Invalid action type reference, missing required fields
• Symptom: Commit/deploy fails with ok: false in validation response
• Fix: Verify action types exist in registry. Check errors array in commit response.

HTTP Action Errors

• Cause: External API returned error status code
• Symptom: Action fails with 4xx/5xx
• Fix: For expected failures (4xx), use error paths instead of failing. Access error data via ${{ ACTIONS.<ref>.error }}.

Secret Access Errors

• Cause: Missing secret, wrong key name, expired credential
• Symptom: Workflow fails on SECRETS.<name>.<key> resolution
• Fix: Verify secret exists in workspace with correct key name via tracecat_search_secrets.

Child Workflow Errors

• Cause: Error in sub-workflow propagated up
• Symptom: Nested error chain (ChildWorkflowFailure > ActivityFailure > original)
• Fix: Inspect innermost cause in EventFailure chain.

Debug Workflow (Step-by-Step)

1. Identify the failure

tracecat_list_executions → find the failed execution
tracecat_get_execution → get full event history

2. Read the error

In the execution events, look for:

• status: FAILED on the event
• failure.message — human-readable error description
• failure.cause — original exception and stack trace
• In compact view: action_error.message

3. Locate the root cause

• Which action failed? Check action_ref and action_name on the failed event
• What was the input? Check action_input on the event
• What did upstream actions return? Check action_result on preceding events

4. Common fix patterns

Deploy-Time Validation

When deploying via tracecat_deploy_workflow, the system validates:

1. Action registry — Each action type must exist in the registry
2. Expression syntax — All ${{ }} expressions in run_if, for_each, retry_until, and inputs
3. Graph connectivity — Checks for unreachable nodes at join points

The commit response contains:

• status: "success" or "failure"
• message: What happened
• errors[]: Per-action validation results with ok, message, detail, action_ref

Retry Policies

Example retry until acknowledgment:

control_flow:
  retry_policy:
    max_attempts: 5
    timeout: 600
  retry_until: ${{ ACTIONS.send_reminder.result.ack == True }}

Error Paths (Branching on Failure)

Since PR #471, actions can define success and error handles:

• On success → next action in the normal flow
• On error → branch to an error-handling action

Access error data from a failed upstream action:

${{ ACTIONS.<failed_action_ref>.error }}

Join Strategies

Use "any" for error-tolerant branches where partial results are acceptable.

Tips

• Always check tracecat_health_check first to rule out connectivity issues
• Use compact execution view for quick triage, full view for deep investigation
• Expression errors are the #1 cause of failures — double-check action slugs
• For flaky integrations, add retry policies rather than error paths
• For expected failures (API 404 = "not found"), use error paths to handle gracefully
• Secrets are purged from memory after execution — they don't persist in logs

Related Skills

• tracecat-mcp-tools-expert — MCP tool reference (use tracecat_validate_workflow before deploying)
• tracecat-workflow-patterns — Correct workflow design patterns
• tracecat-yaml-syntax — Fix YAML/expression syntax errors
• tracecat-integration-expert — Debug integration-specific errors
• tracecat-code-python — Debug Python script failures

Reference Files

• Common Mistakes
• Examples
• README