> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Execution Errors
> List of possible errors occurred during workflow or broadcast execution and their resolutions.
## Pre-Requisite
[Understanding the data structure of logs](/docs/logging)
## Understanding Error Locations
Errors appear in different log types depending on when they occur in the notification pipeline:
**Before workflow starts** - API structure errors, validation errors, authentication failures, trigger condition mismatches
**During workflow processing** - Variable/data errors, template rendering failures, node processing errors, channel computation issues
**Broadcast processing** - Template fetch errors, user profile fetch errors, pre-trigger processing errors
**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](/docs/python-trigger-workflow-from-api#idempotent-requests). |
### 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](/docs/workflows#create-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](/docs/users#creating-user-profile-on-suprsend) |
### 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**.
### User-Related Errors
| 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](/docs/users#creating-user-profile-on-suprsend). If triggering workflow directly via API, pass user channel information in the user instance of your workflow call. Refer [workflow documentation](/docs/trigger-workflow#triggering-workflow-via-api) 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](/docs/users#creating-user-profile-on-suprsend). (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](/docs/users#via-sdk). 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](/docs/users#creating-user-profile-on-suprsend). - All identities for that channel are `inactive` in user profile. Channel can be marked inactive using `unset` or `remove` function via [SDK or API](/docs/users#via-sdk). 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](/docs/python-create-user-profile#1-add-user-channels) for other channel formats. |
| **user's distinct\_id must be present if it's not transient** | Include `distinct_id` in your [workflow](/docs/python-trigger-workflow-from-api#trigger-workflow-from-api) or [event](/docs/python-send-event-data#send-event) payload. If sending to anonymous users, include user channels and set `is_transient: True`. [Learn more](/docs/python-trigger-workflow-from-api#sending-notification-to-anonymous-user) |
| **users - no valid value passed** | Pass `distinct_id` key in your [workflow](/docs/python-trigger-workflow-from-api#trigger-workflow-from-api) or [event](/docs/python-send-event-data#send-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](/docs/python-trigger-workflow-from-api#sending-notification-to-anonymous-user) |
### 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 notification category passed in workflow payload is not present on SuprSend dashboard or you have mistakenly added category name rather than its slug. Click on Notification 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 -> Notification Categories](https://app.suprsend.com/en/staging/settings/notification-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](/reference/user-category-preference). |
| \*\*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](/reference/user-category-preference). |
| **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](/reference/user-category-preference). |
| **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](/reference/user-category-preference). |
| **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](https://develop.suprsend-app.pages.dev/en/staging/brands/default/brand_preference) 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](https://app.suprsend.com/en/production/tenants/). You can create this brand/tenant from [SuprSend dashboard or via your backend SDK / API](/docs/tenants#creating--updating-tenant-on-suprsend-platform). |
### 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](https://www.devtoolsdaily.com/jq_playground/). |
| **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](/docs/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 notification category is missing. Navigate to vendor page on SuprSend dashboard to setup vendor. You can find integration guidelines for all vendors [here](/docs/vendors). |
### Internal Errors
| Error | Solution |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **500: xxxx** | SuprSend Internal server error. Reach out to us on [Slack community](https://join.slack.com/t/suprsendcommunity/shared_invite/zt-3932rw936-XNWY1RC8bsffh4if4ZyoXQ) 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](/docs/lists#1-programmatically-using-sdk--api) or [directly via csv upload](/docs/lists#3-from-ui-using-csv-upload) from [dashboard -> Lists page](https://app.suprsend.com/en/staging/subscribers/subscriber-list/). |
| **SubscriberList Broadcast API: list\_id: `<list_id>` not found** | `<list_id>` doesn't exist in SuprSend. You can create list programmatically [via SDK / API](/docs/lists#1-programmatically-using-sdk--api) or directly by clicking on **"New List"** button on [SuprSend dashboard -> Lists page](https://app.suprsend.com/en/staging/subscribers/subscriber-list/). |
### 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](/docs/users#creating-user-profile-on-suprsend). - All identities for that channel are `inactive` in user profile. Channel can be marked inactive using `unset` or `remove` function via [SDK or API](/docs/users#via-sdk). 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 notification category is missing. Navigate to vendor page on SuprSend dashboard to setup vendor. You can find integration guidelines for all vendors [here](/docs/vendors). |
## 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
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](/docs/python-trigger-workflow-from-api#idempotent-requests).
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](/docs/python-create-user-profile#1-add-user-channels) for other channel formats.
If you are facing an issue which is not covered above, reach out to us on [Slack community](https://join.slack.com/t/suprsendcommunity/shared_invite/zt-3932rw936-XNWY1RC8bsffh4if4ZyoXQ) or via email: [support@suprsend.com](mailto:support@suprsend.com)