Why a Report or Export Didn't Send
Every failed scheduled report, export and recipient carries a stable code and a plain sentence you can show your users, with the full list of codes
When a scheduled report or an export fails, or a recipient isn't reached, the run records why in three parts:
| Field | What it is | Use it to |
|---|---|---|
code | A stable string from the lists below | Decide what your own page shows. Map the code to your own wording if you want different words |
message | A complete, plain sentence that says what happened and what to do | Show it to your users as it is |
detail | The actual error, exactly as it happened | Troubleshoot. Only organization admins receive it |
Map code, never message or detail. Messages can be reworded, and detail is raw text from the system or a provider that changes without notice. Codes don't change: new codes may be added, and a code is never renamed or removed without a release note.
A failure that has no underlying error, such as a cancelled run or a refused export, has no detail.
Reading failures through the API
Three endpoints return failure with code and message. It is null when nothing failed:
- List runs (
GET /api/v1/automations/runs) lists runs, each with itsfailure. Passkind=BRIEFINGfor scheduled reports,kind=EXPORTfor exports. - Get a run's delivery (
GET /api/v1/briefings/{briefingId}/runs/{runId}/delivery) returns each recipient's status andfailurefor a scheduled report run, and the attachments that were left out. - Get an export (
GET /api/v1/exports/{id}) returns an export's status andfailure.
error is still returned beside failure and holds the same text as failure.message.
When the caller is an organization admin, failure also includes detail. Tenant callers never receive it. Use it to troubleshoot, or include it when you contact support; don't show it to end users or parse it.
Runs that failed before codes were introduced have a failure of null and keep their original error text. An export that failed before then reads unexpected, with its original text as message. A cancelled export has failure.code cancelled and an error of null.
A report didn't run
The report wasn't sent to anyone.
| Code | Message |
|---|---|
cancelled | This run was cancelled. |
deleted | This report was deleted while it was running. |
timed_out | This run didn't finish in time and was stopped. Run it again, and contact support if it keeps happening. |
access_lost | This report's dashboard was deleted, or the person it runs as can no longer open it. Restore their access, or reauthorize the report with someone who has access. |
analysis_turned_off | Analysis is turned off for this project, so this report can't run. Ask an admin to turn it on, or change the report to send without analysis. |
slack_not_available | Slack delivery isn't available for this report. Send it by email instead. |
attachment_not_available | This report has an attachment type that isn't available here. Remove it, then save the report. |
setup_incomplete | This report's setup is incomplete or out of date. Open it, check its settings and save it again. |
attachments_failed | This report's attachments couldn't be prepared, so it wasn't sent. Try again, and contact support if it keeps happening. |
instructions_unclear | This report's instructions don't say enough about what to cover. Add more detail, then run it again. |
instructions_too_large | This report's instructions are too long. Shorten them, then run it again. |
no_matching_data | This report couldn't find data that answers its instructions. Check the instructions and the data they refer to, then run it again. |
analysis_failed | This report's analysis couldn't be completed. Try again, and contact support if it keeps happening. |
not_delivered | This report couldn't be delivered to any recipient. See each recipient for the reason. |
partly_delivered | This report reached some recipients but not others. See each recipient for the reason. |
no_recipients | None of this report's recipients has an email address. Add a recipient with an email address, then run it again. |
unexpected | Something went wrong while running this report. Try again, and contact support if it keeps happening. |
unexpected covers every failure without a more specific code. Its detail holds the actual error.
An export didn't finish
Background CSV and Excel exports.
| Code | Message |
|---|---|
deadline | This export took longer than 30 minutes and was stopped. Narrow the filters or remove columns, then try again. |
too_large | This export is larger than the export limit. Narrow the filters or remove columns, then try again. |
access_lost | You no longer have access to some of this data, so the export was stopped. |
data_changed | The data changed while this export was running. Try again. |
query_failed | The data source couldn't complete this export's queries. Try again in a few minutes, and contact support if it keeps happening. |
definition_incomplete | This table's setup is missing something it needs to export, such as a field's source or a calculation's formula. Open the table, check its fields and filters, and save it. Contact support if it keeps happening. |
excel_column_limit | This export has more columns than Excel can hold (16,384). Export as CSV instead. |
excel_row_limit | This export has more rows than Excel can hold (1,048,576). Export as CSV instead. |
excel_size_limit | This export is larger than an Excel file can hold (4 GB of sheet data). Export as CSV instead. |
cancelled | This export was cancelled. |
refused_too_large | This data has more than the export row limit. Apply filters to export it. The message names the limit. |
refused_count_unavailable | We couldn't count this export's rows, so it didn't start. Try again in a few minutes. |
refused_count_unsupported | This table can't export in the background. Apply filters to bring it under the limit. The message names the limit. |
refused_no_rows | There's no data to export. |
unexpected | Something went wrong while preparing this export. Try again, and contact support if it keeps happening. |
The refused_ codes mean the export never started. See Export limits for the limits.
A data refresh didn't finish
Runs that refresh cached data on a schedule.
| Code | Message |
|---|---|
cancelled | This run was cancelled. |
timed_out | This run didn't finish in time and was stopped. Run it again, and contact support if it keeps happening. |
unexpected | Something went wrong while refreshing this data. Try again, and contact support if it keeps happening. |
A recipient wasn't reached
A report can reach some recipients and not others. Each recipient has its own status and failure.
| Code | Channel | Message |
|---|---|---|
email_not_set_up | Email delivery isn't set up, so this report wasn't emailed. | |
email_failed | The email to the recipient couldn't be sent. The next run will try again; contact support if it keeps happening. | |
slack_not_in_channel | Slack | The app isn't in the channel. Add it to the channel, then run again. |
slack_channel_not_found | Slack | The channel can't be found. It may have been deleted or made private; pick another channel. |
slack_channel_archived | Slack | The channel is archived. Pick another channel, then run again. |
slack_disconnected | Slack | Slack is disconnected. Reconnect Slack, then run again. |
slack_missing_permission | Slack | The Slack app is missing a permission it needs. Reconnect Slack, then run again. |
slack_failed | Slack | The post to the channel couldn't be sent. Try again, and contact support if it keeps happening. |
The messages name the actual recipient or channel. When email_failed appears, the email provider's own reason is in detail.
An attachment was left out
The report was sent, but without one of its attachments. This isn't a failure: show these as warnings. Each entry in omissions has a code and a reason sentence that names the attachment.
| Code | What it means |
|---|---|
PDF_ROW_LIMIT_EXCEEDED | The attachment has more rows than a PDF can hold. Switch it to CSV to receive every row. |
PDF_SIZE_LIMIT_EXCEEDED | The attachment is too large for a PDF. Switch a card to CSV, or narrow a dashboard or document with a filter. |
PDF_PAGE_LIMIT_EXCEEDED | The attachment has more pages than a PDF can hold. Narrow it with a filter. |
TABLE_COMPLETENESS_UNVERIFIED | The table couldn't be confirmed complete when the report was sent. Switch it to CSV to receive every row. |
CARD_QUERY_FAILED | The card's data couldn't be loaded when the report was sent. |
RENDER_NOT_READY, RENDER_TIMED_OUT | The attachment didn't finish loading in time. |
EXPORT_JOB_FAILED | The attachment's export couldn't be completed. |
EXCEL_LIMIT_EXCEEDED | The attachment has more columns than Excel can hold. Switch it to CSV. |
EXPORT_ROW_LIMIT_EXCEEDED | The attachment has more rows than the export limit. Narrow it with a filter. |
EXPORT_COUNT_UNAVAILABLE | The attachment's size couldn't be confirmed. It's tried again on the next run. |
EXPORT_NO_ROWS | The attachment has no rows for this run. |
CARD_FILE_LIMIT_EXCEEDED | The card has too many rows, or is too large, for one file. Narrow it with a filter. |
IMAGE_TOO_LARGE | The sheet is too tall for one image. Switch the attachment to PDF. |
DOCUMENT_PAGE_OVERFLOW | Part of the document doesn't fit on its page. Open the report to see which page. |
DOCUMENT_ROW_LIMIT_EXCEEDED | A table in the document has more rows than a report can print. Narrow it with a filter. |
DOCUMENT_SECTION_SETUP | A section in the document isn't set up to print. Open the report and check its sections. |
REPORT_INPUTS_MISSING | The report needs input values that weren't set. Open the report, set them and save it. |
REPORT_NEEDS_RESAVE | The report's saved formatting doesn't match the dashboard. Open the report and save it again. |
ATTACHMENT_UNAVAILABLE | The attachment couldn't be prepared, for any other reason. |