[Linux] Troubleshooting CommonReport Manager delivery failures
Summary: A participant shared a comprehensive troubleshooting guide for dealing with common report delivery issues in the Report Manager, covering failures, delays, and pending statuses. The guide explains the components involved, such as the Scheduler, Engine, and Messaging, and offers specific instructions for log collection and problem resolution. Key issues like 'socket hang up', 'stuck in pending', and 'report failed during initialization' are addressed with potential causes and solutions. The post emphasizes the importance of providing detailed error information and logs when contacting support to expedite the resolution process.
Scheduled reports failing, arriving late, or stuck in pending? This guide maps the most common delivery errors to their cause and fix, and shows exactly which logs to collect so we can resolve your case faster.
Before you start: how delivery works
Understanding the moving parts makes every error below easier to place. Report Manager runs as an add-on on the external-plugins pod and is made up of four cooperating services:
Scheduler — decides when each report runs and holds a limited number of concurrency slots (default: 12 reports in parallel).
Engine — generates the report (PDF, Excel, CSV, or dashboard link) for each recipient.
Exporting service — renders the actual files; heavy pivots and large CSVs live here.
Messaging — pushes live status updates to the Report Manager tab.
Two settings govern throughput and are referenced throughout this guide, both under the Report Manager settings window (gear icon):
Number of simultaneous reports — how many reports run at once before the rest go to the pending queue.
Report Generation Timeout — seconds allowed per recipient before that recipient is marked timed-out (
0= unlimited).
Step 1 — Read the status, then the right log
Open the Report Manager tab and check the Last Run icon and Status column for the affected report:
Red icon — the report failed. Hover for the error message; that string is your entry point into the table below.
Orange icon — completed with warnings (usually a per-recipient timeout or an attachment-size limit).
Pending that never becomes Running — a queue/scheduler problem, not an export problem. Go straight to the "stuck in pending" row.
Which log to collect
Report Manager writes to dedicated logs. Collect the ones matching your deployment and share them with the timestamp of a specific failed run:
Cloud (Sisense-managed): you do not have shell access — instead, enable Support Access on the instance and share the report name, recipient, and the exact date/time of a failed run. We pull the pod logs on our side.
Self-hosted Linux: from
/var/log/sisense/sisense/, collect theexternal-pluginspod log. Depending on the issue, it may also be useful to collect theexporting,exporter-xlsxandquery.
How to speed up your case: When you open a ticket, include all four of these up front: (1) the exact error text, (2) the report name and dashboard used in that report and one affected recipient, (3) the date/time of a failed run in your timezone, and (4) your Sisense version With these, we can locate the failure in the logs on the first pass instead of asking for a second round of details.
Step 2 — Match the symptom to the cause and fix
Find the section that matches your error string or symptom. Causes and fixes below are drawn from recurring, resolved cases.
"Socket hang up" — often on Combined Excel or heavy reports, spiking under load
Most likely cause: Multiple heavy reports run at the same time and compete for resources (common with Live data sources); a downstream request times out and drops the connection. When the underlying query itself fails or times out, the export gives up and the connection is dropped. In some cases a misbehaving add-on returns an error that cascades into the timeout.
What to do: Stagger schedules so heavy reports don't all fire at once. Temporarily disable non-essential add-ons to isolate a culprit. If it persists under normal load, collect the
external-pluginslog around the failure time and open a ticket. When the report's underlying query is failing, also collect thequeryservice logs — see "Collecting query logs" below for how to capture the right slice.
Stuck in "Pending", never runs — including manual runs
Most likely cause: The scheduler is not releasing concurrency slots, so the queue fills and nothing new can start. This is a known defect on older builds.
What to do: Immediate — toggle Reports on hold on then off (or disable and re-enable the report) to reset the queue. Permanent — upgrade to 2026.2.1 or later, where the slot handling is fixed.
"Report failed during initialization phase" — intermittent, succeeds on manual retry
Most likely cause: A timing issue when several reports start at once and the Non-Sisense User email is not configured, so a recipient token resolves as empty.
What to do: Set a valid Non-Sisense User email in the Report Manager settings (required whenever you send to external recipients). Permanent fix: 2026.1.1+.
"ENOENT: no such file or directory" / "Failed during export"
Most likely cause: The export could not read or write an expected file. Frequently caused by an out-of-date export-related add-on or a missing local export path.
What to do: Update Export Modifications (and other export add-ons) to the latest supported version. Verify the Local Export File Path exists and is writable. Disable other add-ons to isolate interference.
Per-recipient timeout (orange "completed with warnings")
Most likely cause: Report generation exceeded the Report Generation Timeout for that recipient — usually a heavy widget or large export. Large CSVs can also exceed the
external-pluginspod memory (1 GB default).What to do: Increase the timeout value, or lighten the report (fewer widgets/rows). For large-CSV failures, raise the
external-pluginspod memory. Ensure any load balancer / reverse proxy request timeout is ≥ 300 seconds.
Intermittent SMTP timeout / authentication error on send
Most likely cause: The report generated fine, but your custom email server refused or timed out the connection.
What to do: Verify custom email server host, port, credentials, and that outbound SMTP is allowed by your firewall. This is outside Report Manager itself.
Collecting query logs for a "socket hang up"
When a socket hang up is driven by the report's underlying query — typically on a Live model or a heavy dashboard — the external-plugins log alone often isn't enough. Also collect the query service logs so we can see whether the query failed, timed out, or was cancelled on the engine side.
Two things to keep in mind when pulling them:
Match the timeframe to the failure. The
queryservice is very high-volume, so capture only the window around the failed run — the minutes immediately before and after the error timestamp — rather than the whole file. A precise time (with timezone) makes the relevant lines easy to find.Older logs may already be archived/rotated. Because of the log volume,
querylogs are rotated frequently and older entries are compressed or moved to archived files. If the failure happened more than a short while ago, the live log may no longer contain it — look in the archived/rotatedquerylogs for that period, or reproduce the failure and collect the logs promptly while they're still live.
Cloud customers don't need to pull these manually — enable Support Access and share the exact failure time; we collect and correlate the query and external-plugins logs on our side.
What to include when you contact us
If the steps above don't resolve it, share the following so we can go straight to the underlying cause instead of asking for more detail:
The exact error text from the report status.
The report name and at least one affected recipient.
The date and time (with timezone) of a specific failed run.
Your Sisense version and whether the instance is Cloud or self-hosted.
Logs: Cloud — enable Support Access; self-hosted — attach the
external-pluginsFor query-driven failures (e.g. socket hang up on a Live model), also include thequeryservice logs for the matching timeframe — check archived/rotated logs if the failure isn't recent.Whether the report is based on a Live model and whether it sends to external recipients.
With a full picture we can pinpoint the underlying cause, confirm whether a known fix applies to your version, and bring anything unresolved to our engineering team for review.
