Workflows troubleshooting

This page covers troubleshooting for Workflows. For setup, see the installation guide.

Have a question? Ask PostHog AI

Emails not sending?

Check that your domain is verified and you’ve added the DNS records correctly.

Spam folder issues?

Ensure SPF/DKIM are valid, and consider setting up DMARC.

Debugging email delivery failures

When an email bounces, is rejected, or receives a complaint, the failure details are logged as entries on the individual workflow invocation. Bounce entries include the bounce type (permanent or transient) and the SMTP diagnostic message. Complaint entries include the feedback type (e.g., "abuse"). Rejections and rendering failures include the specific error details from SES.

To find affected invocations, go to the workflow's Metrics tab and click a metric tile like Bounced or Blocked. This navigates to the Invocations tab with a log filter applied, showing all invocations that experienced that failure type within the selected timeframe.

Variables not populating?

Confirm the property exists on the person profile (e.g. person.name).

Validation errors when enabling?

Validation errors occur when you try to enable a workflow, not when saving. You can save incomplete workflows as drafts and return to them later.

Common validation issues include:

• Missing trigger events
• Incomplete dispatch configuration (e.g., no recipient email address)
• Invalid filter conditions
• Missing required fields in workflow steps

Fix the issues listed in the error message, then try enabling again. Drafts can be archived even if they have validation errors.

Liquid TokenizationError in email templates?

If you see an error like TokenizationError: unexpected character "\"there\"..." when saving an email template, the cause is double quotes inside a Liquid expression. The email builder serializes templates to JSON, which escapes double quotes and breaks the Liquid parser.

Use single quotes around string arguments in filters:

{{ person.properties.first_name | default: 'there' }}

Variable size limit exceeded?

Workflows have a 5KB limit for storing output variables. If your total variable size exceeds this limit, you'll see an error like:

Total variable size after updating '[key names]' exceeds 5KB limit. Use result_path to store only the fields you need.

Solutions:

• Use result_path in your output variable configuration to store only the specific fields you need rather than entire response objects
• Reduce the amount of data being stored in variables
• Split large data across multiple workflow steps if needed

When this error occurs, the workflow's error handling setting determines what happens next:

• on_error: abort - The workflow exits immediately
• on_error: continue - The workflow skips to the next step

Solved community questions