Troubleshooting & FAQ

Flow execution failures

Diagnose and fix Flow execution failures using logs, error patterns, and debugging techniques.

Identifying the problem

  1. Go to Logs
  2. Filter by Status: Failed
  3. Click the failed execution
  4. Review error details

Common Flow failures

Invalid JSON in request body

Error: Unexpected token in JSON at position X

Cause: Malformed JSON in API call or transform step

Fix:

  1. Validate JSON syntax (remove trailing commas, quote strings)
  2. Use JSON.stringify() in transform steps
  3. Test with online JSON validator

Missing required parameter

Error: Missing required field: {fieldName}

Cause: Flow input missing expected field

Fix:

  1. Add validation at Flow start
  2. Provide default values: {{field || "default"}}
  3. Update callers to include required fields

API call returns 500 error

Error: External API returned 500

Cause: Third-party API encountered server error

Fix:

  1. Add retry logic with delay steps
  2. Implement error handling and fallback responses
  3. Contact API provider if persistent

Record not found

Error: Record not found

Cause: A Get Record step found no match (Get Record fails when nothing matches; List Records returns an empty array instead unless you set its On empty option to Fail)

Fix:

  1. For Get Record, add a conditional check: {{getRecord.output != null}}, or set the step’s error handling to continue on error
  2. For List Records, check {{listRecords.output.length}} > 0 instead of a null check
  3. Provide fallback behavior in the else branch
  4. Verify the lookup field and value are correct

Transform step JavaScript error

Error: ReferenceError: X is not defined

Cause: JavaScript syntax error in transform step

Fix:

  1. Check variable spelling and scope
  2. Use const or let to declare variables
  3. Test transform logic in isolation

Debugging workflow

  1. Identify failing step: Check logs to see which step failed
  2. Review input: Inspect data passed to that step
  3. Test in isolation: Run Flow with test data that triggers error
  4. Add logging: Use transform steps with console.log() to inspect values
  5. Fix and verify: Update Flow, test, publish

Preventing failures

Input validation

Add validation at Flow start:

1if (!input.email || !input.email.includes('@')) {
2  throw new Error('Invalid email provided');
3}

Test Flows with edge cases: empty inputs, null values, invalid data, API failures. Proactive testing prevents production failures.

When errors are expected

Some failures are normal and should be handled, not prevented:

  • User provides invalid input → Return clear error message
  • External API temporarily down → Retry or queue for later
  • Record doesn’t exist → Create new Record or use defaults

Design Flows to handle these scenarios gracefully.

Next steps