Troubleshooting Failed Runs

Debug failed automation runs and dead letters

Troubleshooting Failed Runs

When an automation run fails, it means an error occurred while executing a step for a specific contact. Mailnaptic provides detailed error information and a dead letter mechanism to help you diagnose and resolve failures.

Identifying failed runs

1. Open the automation from the Automations list.
2. Go to the Runs tab.
3. Filter by Failed status to see all runs that have encountered errors.
4. Click on a failed run to see the error details.

Common failure causes

Email send failures

• Contact suppressed: The contact was suppressed (e.g., due to a hard bounce) between enrollment and the email send step.
• Domain verification lost: The sending domain became unverified after the automation was activated.
• Template error: The email content contains merge fields that cannot be resolved for this contact.

Condition evaluation failures

• Missing data: A condition references a custom field or tag that has been deleted.
• Invalid configuration: The condition's comparison operator is incompatible with the field type.

System errors

• Database connectivity: A temporary database connection issue prevented the step from executing.
• Worker crash: The automation worker was interrupted during step execution. These are automatically recovered by the stall recovery mechanism.

The dead letter mechanism

When a run fails permanently (after retry attempts are exhausted), it enters a "dead letter" state. Dead letter runs are logged with full context, including:

• The contact's ID and email address.
• The automation and step that failed.
• The error message and stack trace.
• The timestamp of the failure.

Mailnaptic logs dead letter events at the error level, making them visible in your application logs for monitoring and alerting.

Retry behavior

When a step fails with a transient error (like a temporary database issue), the automation worker will retry the step. The run is set to a "retrying" status. If retries succeed, the run continues normally. If retries are exhausted, the run enters the dead letter state.

The stall recovery mechanism automatically handles runs that get stuck in "processing" for more than 10 minutes, resetting them to "retrying" status for another attempt.

Resolving failed runs

1. Read the error message: The run detail shows exactly what went wrong. Start here.
2. Fix the root cause: If it is a configuration issue (deleted tag, missing field, unverified domain), fix the underlying problem.
3. Re-enroll the contact: After fixing the issue, you can manually re-enroll failed contacts into the automation.
4. Monitor for recurrence: After fixing, watch the automation for new failures to confirm the issue is resolved.

Preventing failures

• Test thoroughly: Always test automations with test contacts before activating.
• Use default values: When using merge fields in email content, provide fallback values for contacts with missing data.
• Verify domains: Ensure your sending domain remains verified and properly authenticated.
• Monitor regularly: Check the run monitor periodically for failed runs.
• Keep configurations clean: Do not delete tags or custom fields that are referenced in active automations.

Failed runs are inevitable in any system, but with proper monitoring and the tools Mailnaptic provides, you can identify and resolve issues quickly before they impact a significant portion of your audience.