Flow Troubleshooting
If your flow isn't working as expected, this guide covers the most common issues and how to resolve them.
Flow Not Triggering
If your flow is active but no trips are being created:
1. Check the Flow Status
Make sure the flow is Active, not Draft or Paused. Go to Flows and verify the status badge.
2. Verify the Trigger Event Name
The trigger event name must exactly match what your application sends. Event names are case-sensitive.
- Go to Developer Tools > Event Schemas to see which events Synapse is actually receiving.
- Compare the event name in the schema list with your flow's trigger event setting.
- Common mistakes: extra spaces, different casing (
user_signupvsUser_Signup), typos.
3. Check Entry Conditions
If you have entry conditions set, the event attributes must match those conditions. Try temporarily removing all entry conditions to see if events start triggering the flow.
4. Check the Segment Filter
If your flow uses a segment, the contact must match that segment at the moment the event arrives. Try temporarily removing the segment filter to see if trips start being created.
5. Check Idempotency
Synapse prevents the same contact from entering the same flow for the same event twice. If you're testing with the same event data repeatedly, use a different idempotency key each time.
When testing, send events with a unique idempotency_key each time (e.g., include a timestamp). This prevents deduplication from blocking your test events.
Emails Not Sending
If trips are being created but emails aren't going out:
1. Check for Suppressed Emails
If your template uses the required modifier on any variable, and that data is missing from the contact or event, the email is suppressed (not sent).
Go to Email Logs and search for the contact. Look for emails with a status of Suppressed.
2. Check the Contact's Subscription Status
Emails are only sent to contacts with a subscribed status. If the contact has unsubscribed or has a complained status, no emails will be sent.
3. Check Your Monthly Email Limit
Each plan has a monthly email limit. If you've hit the limit, no more emails can be sent until the next billing cycle or until you upgrade your plan.
Go to Settings > Billing to check your current usage.
4. Check the Sender Domain
Make sure your sender domain is verified. Go to Settings > Sender Domains and confirm the status shows Verified.
5. Check Email Logs for Errors
Go to Email Logs and filter by the flow name. Look for entries with a Failed status and read the error message. Common errors include:
| Error | Cause | Fix |
|---|---|---|
| Invalid email address | Contact's email is malformed | Update the contact's email in your source system |
| Domain not verified | Sender domain setup is incomplete | Complete domain verification in Settings |
| Rate limited | Too many emails sent too quickly | Wait and retry, or upgrade your plan |
| Template render error | NLT expression references missing data | Fix the template or ensure data is being sent |
Duplicate Emails
Synapse has built-in protections against duplicate sends, but here are things to check:
1. Multiple Flows for the Same Event
If you have multiple active flows with the same trigger event, each flow will independently process the event. This is by design, but make sure you don't have unintended duplicate flows.
2. Application Sending Duplicate Events
If your application sends the same event multiple times (e.g., due to retries), Synapse's idempotency guard should catch this. Make sure your application includes a consistent idempotency_key with each event.
3. Flow Edited While Active
If you edit an active flow, existing trips continue with the original configuration while new trips use the updated version. This should not cause duplicates, but be aware of the two versions running simultaneously.
Wait Steps Not Resuming
If contacts seem stuck at a wait step:
1. Check the Wait Duration
Make sure the wait duration is what you intended. A wait of 24h means 24 hours, not 24 minutes. Common duration formats:
| Format | Meaning |
|---|---|
1h | 1 hour |
24h | 24 hours (1 day) |
7d | 7 days |
2w | 2 weeks |
2. Check Trip Status
Open the flow's Trips tab and look for the contact's trip. If the trip status shows Terminated, the flow was stopped while the contact was waiting. If it shows Failed, there was a processing error. Active trips at a wait step will resume automatically when the wait duration expires.
3. System Issues
If many trips across multiple flows are stuck, there may be a system issue with the background workers. Contact support if this persists.
Condition Steps Not Working as Expected
1. Check the Condition Logic
Open the flow and review the condition step configuration. Make sure:
- The correct check type is selected (event existence vs. contact property vs. event attribute)
- The comparison value is correct and matches the data type
- The "if true" and "if false" actions are set correctly
2. Verify the Data
Check the contact's profile or event data to confirm the value you're checking actually exists and matches what you expect. Go to Contacts, find the contact, and review their properties and event timeline.
Condition steps evaluate data at the moment they execute, not at the time the flow was triggered. If you're checking whether a contact performed an event since entering the flow, make sure enough time has passed for that event to arrive.
Getting More Help
If you've tried the steps above and your issue persists:
- Check the Email Logs for detailed error messages.
- Check the Developer Tools > DLQ Viewer for failed processing attempts (Developer and Admin roles only).
- Contact your workspace admin to review system logs.