Skip to main content

Debugging Workflows

Even well-designed workflows can have issues. This guide teaches you how to identify problems, understand error messages, and fix common issues in your workflows.

Time to complete: 20 minutes

Debugging Mindset​

When a workflow fails, follow this process:

1. IDENTIFY   → What failed? (Which node? What error?)
2. REPRODUCE  → Can you trigger it again?
3. INVESTIGATE → What data caused it?
4. UNDERSTAND → Why did it fail?
5. FIX        → Make the correction
6. VERIFY     → Test the fix

Finding the Problem​

Step 1: Check Execution Status​

Go to Automation → Executions or the workflow's execution panel:

Executions:
ex_abc123  ❌ Failed    2 min ago    transformdata_1
           └─────────────────────────────────────────┘
                                     ↑ Failed node

Step 2: Open Execution Details​

Click the failed execution to see:

  • Which node failed
  • Error message
  • Input data at failure point

Step 3: Review the Error​

┌─────────────────────────────────────────────────────────────┐
│ ❌ Error in transformdata_1                                  │
├─────────────────────────────────────────────────────────────┤
│ TypeError: Cannot read property 'email' of undefined        │
│                                                             │
│ at transform (line 3)                                       │
│   const email = input.contact.email;                        │
│                       ↑                                     │
│                  input.contact is undefined                 │
└─────────────────────────────────────────────────────────────┘

Common Error Types​

1. Variable Not Found​

Error:

Cannot read property 'X' of undefined

Cause: Accessing a property on undefined/null

Example:

// This fails if contact doesn't exist
const email = input.contact.email;

Fix:

// Use optional chaining
const email = input.contact?.email;

// Or with default
const email = input.contact?.email || "no-email";

2. Invalid Variable Path​

Error:

Variable not found: webhooktrigger_1.playload.email

Cause: Typo in variable path

Fix: Check spelling

❌ {{webhooktrigger_1.playload.email}}
✅ {{webhooktrigger_1.payload.email}}

3. Node Not Executed​

Error:

Variable 'transformdata_1.result' not available

Cause: Trying to use output from a node that didn't run (different branch)

Fix: Ensure node is in the execution path, or handle missing data

4. Integration Error​

Error:

Authentication failed: Invalid API key

Cause: Integration credentials expired or invalid

Fix:

  1. Go to Settings → Integrations
  2. Reconnect the integration
  3. Update credentials if needed

5. Timeout Error​

Error:

Execution timed out after 60 seconds

Cause: Node or workflow took too long

Fix:

  • Increase timeout in node settings
  • Optimize slow operations
  • Add pagination for large data

6. Rate Limit Error​

Error:

429 Too Many Requests

Cause: Calling external API too frequently

Fix:

  • Add Delay node between API calls
  • Batch requests if possible
  • Use retry with backoff

Debugging Tools​

1. Test Mode​

Run workflows with sample data:

  1. Click Test in toolbar
  2. Enter test input
  3. Watch execution in real-time
  4. Click nodes to see data

Best for: Testing changes before activating

2. Execution Replay​

Visualize past executions:

  1. Open failed execution
  2. Click Replay on Canvas
  3. See exactly what happened
  4. Click nodes to inspect data

Best for: Understanding what went wrong

3. Run From Here​

Re-run from a specific node:

  1. Click on any node
  2. Click Run From Here
  3. Uses data from previous execution
  4. Only runs from that node forward

Best for: Testing fixes without full re-run

4. Console Logging​

Add logging to Transform nodes:

console.log("Input data:", input);
console.log("Contact:", input.contact);
console.log("Processing email:", input.contact?.email);

// Your transform logic
return { processed: true };

View output in execution Console tab.

5. Debug Transform​

Add a Transform node just to inspect data:

// Debug node - see everything
return {
  _debug: true,
  all_input: input,
  specific_node: input.webhooktrigger_1,
  keys: Object.keys(input)
};

Debugging Scenarios​

Scenario 1: Email Not Sending​

Symptoms: Email Send node shows success, but no email received

Debug steps:

  1. Check node output - is success: true?
  2. Verify recipient email is correct
  3. Check spam folder
  4. Verify integration is working (test in Settings)
  5. Check email provider logs

Common causes:

  • Wrong recipient variable
  • Email in spam
  • Integration needs reconnection
  • Provider limits exceeded

Scenario 2: Wrong Data in Output​

Symptoms: Workflow completes but produces wrong results

Debug steps:

  1. Replay the execution
  2. Check each node's input/output
  3. Find where data becomes wrong
  4. Fix that node

Example fix:

// Before (wrong)
const name = input.contact.name;  // Undefined

// After (correct)
const name = input.webhooktrigger_1.payload.contact.name;

Scenario 3: Condition Taking Wrong Path​

Symptoms: Workflow goes True when it should go False (or vice versa)

Debug steps:

  1. Click on Condition node in replay
  2. Check evaluated_value - what was actually checked?
  3. Check result - true or false?
  4. Compare against expected

Common causes:

// String "0" is truthy
"0" == true  // This takes True path!

// Use strict comparison
value === 0  // Number comparison
value === "0" // String comparison

Scenario 4: Loop Not Processing All Items​

Symptoms: Loop only processes some items

Debug steps:

  1. Check Max Iterations setting
  2. Check for errors in loop body
  3. Check Continue on Error setting
  4. Review individual iteration results

Fix:

Max Iterations: 1000  (increase if needed)
☑ Continue on Error   (don't stop on single failure)

Scenario 5: Webhook Not Triggering​

Symptoms: External system sends data but workflow doesn't run

Debug steps:

  1. Is workflow active?
  2. Is correct webhook URL used?
  3. Is data format correct (JSON)?
  4. Check webhook logs in Settings → Webhooks

Common causes:

  • Workflow inactive
  • Wrong webhook URL
  • Malformed request body
  • Authentication required but not provided

Debugging Checklist​

For Any Failed Execution​

  • Identify the failed node
  • Read the error message
  • Check the input data
  • Verify variable paths
  • Check integration status
  • Test with known-good data

For Variable Issues​

  • Verify node alias spelling
  • Check the full path
  • Confirm source node executed
  • Use optional chaining (?.)
  • Add default values

For Integration Issues​

  • Test integration separately
  • Check credentials
  • Verify API limits
  • Check network/firewall

For Logic Issues​

  • Replay execution step-by-step
  • Check condition evaluations
  • Verify data types (string vs number)
  • Test edge cases

Preventive Debugging​

Add Validation Early​

// At start of workflow
const data = input.webhooktrigger_1.payload;

if (!data.email) {
  throw new Error("Email is required");
}

if (!data.email.includes('@')) {
  throw new Error("Invalid email format");
}

return { validated: true, data };

Use Defensive Coding​

// Always handle missing data
const contact = input.contact || {};
const email = contact.email || "unknown@example.com";
const name = contact.name || "Friend";

Log Important Steps​

console.log(`Starting process for ${input.contact?.email}`);
// ... do work ...
console.log(`Completed successfully`);

Test Edge Cases​

Test your workflow with:

  • Empty values
  • Missing fields
  • Very long strings
  • Special characters
  • Large arrays
  • Null values

Advanced Debugging​

Trace Execution Path​

For complex workflows with multiple branches:

// Add to each major node
console.log(`[TRACE] Reached node: transform_step_1`);
console.log(`[TRACE] Current data: ${JSON.stringify(input.key_field)}`);

Compare Executions​

Compare a working execution with a failed one:

  1. Open both execution details
  2. Compare trigger data
  3. Find the difference
  4. That difference likely caused the failure

Isolate the Problem​

  1. Create a simplified test workflow
  2. Copy just the problematic nodes
  3. Test with controlled input
  4. Once fixed, apply to main workflow

Getting Help​

Information to Gather​

When asking for help, include:

  1. Workflow name/description
  2. Execution ID
  3. Full error message
  4. Input data (sanitized)
  5. Expected vs actual behavior

Support Channels​

Quick Reference​

Common Errors & Fixes​

ErrorLikely CauseFix
Cannot read property 'X' of undefinedMissing dataUse ?. optional chaining
Variable not foundWrong pathCheck spelling, use picker
Authentication failedBad credentialsReconnect integration
TimeoutToo slowIncrease timeout, optimize
429 Too Many RequestsRate limitedAdd delays

Debugging Tools​

Test Mode       → Run with sample data
Execution Replay → Visualize past runs
Run From Here   → Re-run from specific node
Console Log     → Print debug info
Debug Transform → Inspect all data

Debugging Process​

1. Find failed node
2. Read error message
3. Check input data
4. Understand the cause
5. Fix the issue
6. Test the fix

Next Steps​

Continue with:

  1. Error Handling - Build resilient workflows
  2. Testing Workflows - Prevent issues
  3. Best Practices - Write debuggable workflows
Last updated on