Semaphor

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:

FieldWhat it isUse it to
codeA stable string from the lists belowDecide what your own page shows. Map the code to your own wording if you want different words
messageA complete, plain sentence that says what happened and what to doShow it to your users as it is
detailThe actual error, exactly as it happenedTroubleshoot. 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 its failure. Pass kind=BRIEFING for scheduled reports, kind=EXPORT for exports.
  • Get a run's delivery (GET /api/v1/briefings/{briefingId}/runs/{runId}/delivery) returns each recipient's status and failure for a scheduled report run, and the attachments that were left out.
  • Get an export (GET /api/v1/exports/{id}) returns an export's status and failure.

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.

CodeMessage
cancelledThis run was cancelled.
deletedThis report was deleted while it was running.
timed_outThis run didn't finish in time and was stopped. Run it again, and contact support if it keeps happening.
access_lostThis 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_offAnalysis 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_availableSlack delivery isn't available for this report. Send it by email instead.
attachment_not_availableThis report has an attachment type that isn't available here. Remove it, then save the report.
setup_incompleteThis report's setup is incomplete or out of date. Open it, check its settings and save it again.
attachments_failedThis report's attachments couldn't be prepared, so it wasn't sent. Try again, and contact support if it keeps happening.
instructions_unclearThis report's instructions don't say enough about what to cover. Add more detail, then run it again.
instructions_too_largeThis report's instructions are too long. Shorten them, then run it again.
no_matching_dataThis report couldn't find data that answers its instructions. Check the instructions and the data they refer to, then run it again.
analysis_failedThis report's analysis couldn't be completed. Try again, and contact support if it keeps happening.
not_deliveredThis report couldn't be delivered to any recipient. See each recipient for the reason.
partly_deliveredThis report reached some recipients but not others. See each recipient for the reason.
no_recipientsNone of this report's recipients has an email address. Add a recipient with an email address, then run it again.
unexpectedSomething 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.

CodeMessage
deadlineThis export took longer than 30 minutes and was stopped. Narrow the filters or remove columns, then try again.
too_largeThis export is larger than the export limit. Narrow the filters or remove columns, then try again.
access_lostYou no longer have access to some of this data, so the export was stopped.
data_changedThe data changed while this export was running. Try again.
query_failedThe data source couldn't complete this export's queries. Try again in a few minutes, and contact support if it keeps happening.
definition_incompleteThis 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_limitThis export has more columns than Excel can hold (16,384). Export as CSV instead.
excel_row_limitThis export has more rows than Excel can hold (1,048,576). Export as CSV instead.
excel_size_limitThis export is larger than an Excel file can hold (4 GB of sheet data). Export as CSV instead.
cancelledThis export was cancelled.
refused_too_largeThis data has more than the export row limit. Apply filters to export it. The message names the limit.
refused_count_unavailableWe couldn't count this export's rows, so it didn't start. Try again in a few minutes.
refused_count_unsupportedThis table can't export in the background. Apply filters to bring it under the limit. The message names the limit.
refused_no_rowsThere's no data to export.
unexpectedSomething 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.

CodeMessage
cancelledThis run was cancelled.
timed_outThis run didn't finish in time and was stopped. Run it again, and contact support if it keeps happening.
unexpectedSomething 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.

CodeChannelMessage
email_not_set_upEmailEmail delivery isn't set up, so this report wasn't emailed.
email_failedEmailThe email to the recipient couldn't be sent. The next run will try again; contact support if it keeps happening.
slack_not_in_channelSlackThe app isn't in the channel. Add it to the channel, then run again.
slack_channel_not_foundSlackThe channel can't be found. It may have been deleted or made private; pick another channel.
slack_channel_archivedSlackThe channel is archived. Pick another channel, then run again.
slack_disconnectedSlackSlack is disconnected. Reconnect Slack, then run again.
slack_missing_permissionSlackThe Slack app is missing a permission it needs. Reconnect Slack, then run again.
slack_failedSlackThe 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.

CodeWhat it means
PDF_ROW_LIMIT_EXCEEDEDThe attachment has more rows than a PDF can hold. Switch it to CSV to receive every row.
PDF_SIZE_LIMIT_EXCEEDEDThe attachment is too large for a PDF. Switch a card to CSV, or narrow a dashboard or document with a filter.
PDF_PAGE_LIMIT_EXCEEDEDThe attachment has more pages than a PDF can hold. Narrow it with a filter.
TABLE_COMPLETENESS_UNVERIFIEDThe table couldn't be confirmed complete when the report was sent. Switch it to CSV to receive every row.
CARD_QUERY_FAILEDThe card's data couldn't be loaded when the report was sent.
RENDER_NOT_READY, RENDER_TIMED_OUTThe attachment didn't finish loading in time.
EXPORT_JOB_FAILEDThe attachment's export couldn't be completed.
EXCEL_LIMIT_EXCEEDEDThe attachment has more columns than Excel can hold. Switch it to CSV.
EXPORT_ROW_LIMIT_EXCEEDEDThe attachment has more rows than the export limit. Narrow it with a filter.
EXPORT_COUNT_UNAVAILABLEThe attachment's size couldn't be confirmed. It's tried again on the next run.
EXPORT_NO_ROWSThe attachment has no rows for this run.
CARD_FILE_LIMIT_EXCEEDEDThe card has too many rows, or is too large, for one file. Narrow it with a filter.
IMAGE_TOO_LARGEThe sheet is too tall for one image. Switch the attachment to PDF.
DOCUMENT_PAGE_OVERFLOWPart of the document doesn't fit on its page. Open the report to see which page.
DOCUMENT_ROW_LIMIT_EXCEEDEDA table in the document has more rows than a report can print. Narrow it with a filter.
DOCUMENT_SECTION_SETUPA section in the document isn't set up to print. Open the report and check its sections.
REPORT_INPUTS_MISSINGThe report needs input values that weren't set. Open the report, set them and save it.
REPORT_NEEDS_RESAVEThe report's saved formatting doesn't match the dashboard. Open the report and save it again.
ATTACHMENT_UNAVAILABLEThe attachment couldn't be prepared, for any other reason.

On this page