Execution Errors

Pre-Requisite

Understanding the data structure of logs

Understanding Error Locations

Errors appear in different log types depending on when they occur in the notification pipeline:

Request Logs

Before workflow starts - API structure errors, validation errors, authentication failures, trigger condition mismatches

Workflow Execution Logs

During workflow processing - Variable/data errors, template rendering failures, node processing errors, channel computation issues

Broadcast Execution Logs

Broadcast processing - Template fetch errors, user profile fetch errors, pre-trigger processing errors

Message Logs

After trigger - Delivery attempt errors, vendor communication errors, template rendering during message preparation

Use the idempotency key to trace errors across all log types. If you don’t see a log at one level, check the level above using the idempotency key.

API Errors (Request Logs)

These errors occur at the API/SDK request level, before workflow processing begins. They appear in Request Logs.

Idempotency Key Errors

Error	Solution
2 API requests have the same idempotency key	Try passing another idempotency key in your workflow or event payload. SuprSend supports idempotency to ensure that requests can be retried safely without duplicate processing. If SuprSend receives more than one request with the same idempotency_key in a 24 hour window, it will only process the first request and skip all other requests. Learn more about idempotency key here.

Workflow/Event Errors

Error	Solution
If workflow is triggered via event and there is no active workflow associated with that event	Check if there is an active workflow created on SuprSend dashboard with the given event name. If not, create a workflow on SuprSend dashboard.
Non-existent workflow slug	Verify the workflow slug exists in your workspace. You can search with `template_slug` using global search `⌘ + K` on dashboard.
Trigger condition or schema mismatches	If your API request returns 200 but you don’t see a workflow execution, it usually means trigger conditions didn’t match. Check your event properties against workflow trigger conditions.

Request Structure Errors

Error	Solution
Invalid API structure or missing required fields	Check your request payload structure. Ensure all required fields are present and properly formatted.
Invalid recipient format	Ensure you’re using the correct format. For events, use `distinct_id` instead of `recipient`. For workflows, pass user channel information correctly.
Non-existent distinct_id or user ID	If triggering via event, create the user profile first. If triggering via workflow API, pass user channel information in the user instance. Create user profile via API or SDK

Authentication Errors

Error	Solution
Authentication/Authorization Errors	Verify your API keys are valid and have sufficient permissions.

Workflow Processing Errors (Workflow Execution Logs)

These errors occur during workflow processing, after the request has been accepted. They appear in Workflow Execution Logs.

Error	Solution
no user found with distinct_id: `<distinct_id>`	If triggering notification via event, user needs to be created beforehand. Create user profile via API or SDK. If triggering workflow directly via API, pass user channel information in the user instance of your workflow call. Refer workflow documentation of your respective backend SDK.
no active/preferred channels found for user with distinct_id:`<distinct_id>`	User doesn’t have any applicable active channels in their profile. Applicable channel is the subset of `template group channel`, `channels specified in workflow $channels key`. This could happen for 2 major reasons: (1) User doesn’t have that channel set in their profile. If the workflow is triggered via event, user’s channel is derived from the existing user profile. Create user profile via API or SDK. (2) All identities for that channel are `inactive` in user profile. Channel can be marked inactive using `unset` or `remove` function via SDK or API. SuprSend also marks the channel identity inactive for email and WhatsApp in case of hard errors from vendor end, such as bounced email addresses, unregistered WhatsApp numbers. This is done to safeguard your email domain authority or WhatsApp rating if you continue to send notifications to users who have reported or marked your email or messages as spam. Additionally, this helps in WhatsApp cost saving, as vendor charges for every processed request. Inactive marking period by SuprSend is 15 days for WhatsApp and 90 days for email.
template: live channels: [channel_array], but no respective user (subscribed-)channels present	User profile doesn’t have any active channel from the channels available in template group. This could happen for 2 major reasons: - User doesn’t have that channel set in their profile. If the workflow is triggered via event, user’s channel is derived from the existing user profile. Create user profile via API or SDK. - All identities for that channel are `inactive` in user profile. Channel can be marked inactive using `unset` or `remove` function via SDK or API. SuprSend also marks the channel identity inactive for email and WhatsApp in case of hard errors from vendor end, such as bounced email addresses, unregistered WhatsApp numbers. This is done to safeguard your email domain authority or WhatsApp rating if you continue to send notifications to users who have reported or marked your email or messages as spam. Additionally, this helps in WhatsApp cost saving, as vendor charges for every processed request. Inactive marking period by SuprSend is 15 days for WhatsApp and 90 days for email.
all channel identities provided for user are invalid	Check channel format. Supported formats: - SMS, WhatsApp: `+15555555555` (country code is mandatory) - Email: `support@suprsend.com` Refer here for other channel formats.
user’s distinct_id must be present if it’s not transient	Include `distinct_id` in your workflow or event payload. If sending to anonymous users, include user channels and set `is_transient: True`. Learn more
users - no valid value passed	Pass `distinct_id` key in your workflow or event payload.
channel details missing for transient user	Pass channel identities in users key if sending notification to anonymous user with `is_transient: True` set. Add channel identity as `"$email":["abc@example.com"]` in your users object. Learn more

Template Errors

Error	Solution
TemplateGroup `<template_slug>` not found	This error occurs when, (1) the template with given template_slug is not present in your workspace. You can search with `template_slug` using global search `⌘ + K` on dashboard to verify this. (2) there is no published template version available for the channel (3) you have mistakenly passed template name instead of template slug in your workflow payload. You can get template_slug by clicking on copy icon next to template name on template details page.
`<channel>`: template rendering failed error: “`<variable_key>`” not defined in [object Object]	Certain variables with `variable_key` exist in the template but are not added in workflow data or event properties. Add the missing variable in your workflow data or event properties.
`<channel_slug>`: template rendering error error: Cannot read properties of undefined (reading ‘0’)	This error generally occurs when you are using handlebars helpers in your template on a nested object and the variable referenced inside the helper has parent key missing. For instance, if you have `{{default location.city "your place"}}` helper in your template, and the workflow data has `location` key missing, this error will occur. Ensure parent keys exist in your data.

Category & Preference Errors

Error	Solution
NotificationCategory `<category_slug>` not found	The preference category passed in workflow payload is not present on SuprSend dashboard or you have mistakenly added category name rather than its slug. Click on Preference category name to copy the slug. Please note only published categories can be used in workflows. If you have your category available in draft version, publish the changes before triggering the workflow. Navigate to Settings -> Preference Categories to see all available categories. Click on Category name to copy slug.
user not subscribed to category: `<category_slug>`	User has opted_out from this category. This could happen either if the default user preference for this category is `opt_out` or if the default preference is `opt_in`, then user has explicitly opted_out of this category. You can get user preference setting for that particular category using HTTP API.
user has unsubscribed from all-channels for category:	User has opted_out from this category. This could happen either if the default user preference for this category is `opt_out` or if the default preference is `opt_in`, then user has explicitly opted_out of this category. You can get user preference setting for that particular category using HTTP API.
no (subscribed-)channels found for user. category: `<category_slug>`	User has opted_out from this category. This could happen either if the default user preference for this category is `opt_out` or if the default preference is `opt_in`, then user has explicitly opted_out of this category. You can get user preference setting for that particular category using HTTP API.
user has unsubscribed from channels `<channel_array>` for category: `<category_slug>`	User has opted_out from the given channel list for `category_slug`. You can get user preference setting for that particular category using HTTP API.
NotificationCategory `<category_slug>` not applicable to tenant/brand `<brand_id>`	This means that brand’s default preference for the `category_slug` is turned off for `brand_id`. To check default preference setting of each brand [now called tenant], navigate to default preferences tab on brand details page.

Tenant/Brand Errors

Error	Solution
brand doesn’t exist with id: `<brand_id>`	The `brand_id` doesn’t exist in the given SuprSend Workspace. Check for available brands [now called tenants] on SuprSend dashboard -> tenants page. You can create this brand/tenant from SuprSend dashboard or via your backend SDK / API.

Configuration Errors

Error	Solution
recipient: error evaluating jq-expression `<recipient_expression>`, could not be resolved from event properties	This error occurs when you have overridden the recipient configuration in your workflow, and the jq-expression added in the recipient field is throwing an error or returning null value. To troubleshoot: 1. Navigate to the workflow details page by clicking on the workflow name in the logs. 2. Check the jq-expression added in the recipient field. 3. The recipient jq-expression utilizes event properties JSON for parsing. Validate the output of your jq-expression by adding property JSON here.
invalid duration-format [TTL duration]. valid format [xx]d[xx]h[xx]m[xx]s	This error occurs when TTL format in the smart delivery block is incorrect. The correct TTL format is `[xx]d[xx]h[xx]m[xx]s` where d = day, h = hour, m = minute, s = second. for example - `1d2h30m` would indicate a Time to live (TTL) is 1 day 2 hours 30 minutes.
invalid duration-format . valid format [xx]d[xx]h[xx]m[xx]s	This error occurs when time-duration format in the delay block is incorrect. The correct format is `[xx]d[xx]h[xx]m[xx]s` where d = day, h = hour, m = minute, s = second. for example - `1d2h30m` would indicate a delay of 1 day 2 hours 30 minutes.
no vendor configured for channel: and category: `<notification_category>` and id-provider:	This happens when vendor configuration for the given channel and preference category is missing. Navigate to vendor page on SuprSend dashboard to setup vendor. You can find integration guidelines for all vendors here.

Internal Errors

Error	Solution
500: xxxx	SuprSend Internal server error. Reach out to us on Slack community for assistance with this issue.

Broadcast Processing Errors (Broadcast Execution Logs)

These errors occur during broadcast processing. They appear in Broadcast Execution Logs.

List Errors

Error	Solution
SubscriberList Broadcast API: subscribers list is empty for list_id:`<list_id>`	List doesn’t have any users added. You can either sync users programmatically via SDK / API or directly via csv upload from dashboard -> Lists page.
SubscriberList Broadcast API: list_id: `<list_id>` not found	`<list_id>` doesn’t exist in SuprSend. You can create list programmatically via SDK / API or directly by clicking on “New List” button on SuprSend dashboard -> Lists page.

Template Errors

Error	Solution
SubscriberList Broadcast API: TemplateGroup `<template_slug>` not found	This error occurs when, - the template with given template_slug is not present in your workspace. You can search with `template_slug` using global search `⌘ + K` on dashboard to verify this. - there is no published template version available for the channel - you have mistakenly passed template name instead of template slug in your workflow payload. You can get template_slug by clicking on copy icon next to template name on template details page.
SubscriberList Broadcast API: template: broadcast channels: `<channel_array>` are not live	This error occurs when none of the channels mentioned in broadcast `channels` key is published in the template group.
SubscriberList Broadcast API: `<channel>`: template rendering failed error: “`<variable_key>`” not defined in [object Object]	Certain variables with `variable_key` exist in the template but not part of broadcast data or user properties if you are using `$user` variable in the template.

User Profile Errors

Error	Solution
SubscriberList Broadcast API: template: broadcast applicable live channels: [channel_list], but no respective user channels present	User profile doesn’t have any active channel from the channels available in template group. This could happen for 2 reasons: - User doesn’t have that channel set in their profile. If the workflow is triggered via event, user’s channel is derived from the existing user profile. Create user profile via API or one of our SDKs. - All identities for that channel are `inactive` in user profile. Channel can be marked inactive using `unset` or `remove` function via SDK or API. SuprSend also marks the channel identity inactive for email and WhatsApp in case of hard errors from vendor end, such as bounced email addresses, unregistered WhatsApp numbers. This is done to safeguard your email domain authority or WhatsApp rating if you continue to send notifications to users who have reported or marked your email or messages as spam. Additionally, this helps in WhatsApp cost saving, as vendor charges for every processed request. Inactive marking period by SuprSend is 15 days for WhatsApp and 90 days for email.

Configuration Errors

Error	Solution
SubscriberList Broadcast API: trigger_at must be in ISO 8601 format…	This error occurs when time-duration format in the `trigger_at` key is incorrect. The correct format ISO 8601 timestamp. for example - `2024-01-01T05:30:00Z` indicates that the notification will be triggered at 1 Jan, 2024 5:30 AM UTC.
SubscriberList Broadcast API: no vendor configured for channel: `<channel_name>` and category: `<notification_category>` and id-provider: `<vendor_name>`	This happens when vendor configuration for the given channel and preference category is missing. Navigate to vendor page on SuprSend dashboard to setup vendor. You can find integration guidelines for all vendors here.

Notification Trigger Errors (Message Logs)

These errors occur after a notification is triggered. They appear in Message Logs.

Vendor Errors

Error	Solution
Trigger failed or Failure by Vendor	Trigger Failed occurs in two scenarios: (1) SuprSend internal failures - missing channel info, template rendering failures; (2) Vendor rejections - invalid template, credential errors, bad email/phone format. Failure by Vendor occurs when the vendor accepted the request but failed to deliver. You’ll see `Trigger failed` or `Failure by Vendor` status in the logs. Hover over the ‘i’ icon to view the error message. For detailed troubleshooting, refer to individual vendor guides. Check vendor-specific error documentation.

Frequently Asked Questions

I triggered an event but it doesn't appear in dashboard logs?

We currently do not track individual event triggers unless it’s associated with a workflow. If you don’t see an event trigger in logs, check if there are active workflows linked to that event on SuprSend dashboard.Another reason could be if you are using idempotency key and 2 requests have the same idempotency key. SuprSend supports idempotency to ensure that requests can be retried safely without duplicate processing. If SuprSend receives another request with the same idempotency_key in a 24 hour span, it will skip processing those requests.Learn more about idempotency key here.

I added channels to the user profile, but they are not reflected in subscriber profile on SuprSend dashboard?

Check the format of value passed in user channels. Channel will not be updated in profile if the format is incorrect. Supported format for each channel:

SMS, WhatsApp: +15555555555 (country code is mandatory)
Email: abc@example.com

Refer here for other channel formats.

If you are facing an issue which is not covered above, reach out to us on Slack community or via email: support@suprsend.com

GETTING STARTED

CORE CONCEPTS

WORKFLOW BUILDER

Notification Inbox

PREFERENCE CENTRE

VENDOR INTEGRATION GUIDE

INTEGRATIONS

MONITORING & DEBUGGING

MANAGE YOUR ACCOUNT

Pre-Requisite

Understanding Error Locations

Request Logs

Workflow Execution Logs

Broadcast Execution Logs

Message Logs

API Errors (Request Logs)

Idempotency Key Errors

Workflow/Event Errors

Request Structure Errors

Authentication Errors

Workflow Processing Errors (Workflow Execution Logs)

Template Errors

Category & Preference Errors

Tenant/Brand Errors

Configuration Errors

Internal Errors

Broadcast Processing Errors (Broadcast Execution Logs)

List Errors

Template Errors

User Profile Errors

Configuration Errors

Notification Trigger Errors (Message Logs)

Vendor Errors

Frequently Asked Questions

​Pre-Requisite

​Understanding Error Locations

Request Logs

Workflow Execution Logs

Broadcast Execution Logs

Message Logs

​API Errors (Request Logs)

​Idempotency Key Errors

​Workflow/Event Errors

​Request Structure Errors

​Authentication Errors

​Workflow Processing Errors (Workflow Execution Logs)

​User-Related Errors

​Template Errors

​Category & Preference Errors

​Tenant/Brand Errors

​Configuration Errors

​Internal Errors

​Broadcast Processing Errors (Broadcast Execution Logs)

​List Errors

​Template Errors

​User Profile Errors

​Configuration Errors

​Notification Trigger Errors (Message Logs)

​Vendor Errors

​Frequently Asked Questions

Pre-Requisite

Understanding Error Locations

API Errors (Request Logs)

Idempotency Key Errors

Workflow/Event Errors

Request Structure Errors

Authentication Errors

Workflow Processing Errors (Workflow Execution Logs)

User-Related Errors

Template Errors

Category & Preference Errors

Tenant/Brand Errors

Configuration Errors

Internal Errors

Broadcast Processing Errors (Broadcast Execution Logs)

List Errors

Template Errors

User Profile Errors

Configuration Errors

Notification Trigger Errors (Message Logs)

Vendor Errors

Frequently Asked Questions