Why Apache Superset alerts and reports stop arriving
A scheduled dashboard report or threshold alert that stops arriving usually fails silently, because nothing in the Superset web interface reports that a background job did not run. The chain between the scheduler, the Celery worker, the screenshot step and the delivery channel is where most failures sit. According to the Superset architecture documentation, alerts and reports, async queries and dashboard thumbnails depend on the caching layer and the worker components, and most installations use Redis and Celery for them. A missing link in that chain looks the same from the recipient's side: no message.
This troubleshooting is needed when a team notices that a report or alert has gone quiet, when a new delivery channel or Superset upgrade has been introduced, or when a worker, beat or Redis change has been made in the infrastructure. Before changing anything, confirm which components your deployment actually runs, where the beat scheduler lives, which worker executes report jobs, and which user the executor runs as. Those answers determine which of the checks in the following sections apply to your environment. The architecture documentation is the right reference for the component layout, and your own deployment records should confirm it.
DeployOpen does not guarantee a fix without an environment review. The same symptom can come from a stopped beat process, a worker that cannot launch a headless browser, an SMTP or Slack configuration problem, or a dashboard too slow to render within the configured limits, and each needs different evidence. A review of your configuration, container image, logs and scheduled job records is the starting point, and any fix is agreed in writing against that review.
Which component to check first when a report fails
This sequence moves from the infrastructure a report depends on toward the delivery itself, so you find the failing layer before changing any configuration. Each check narrows the search to one component, and the last check confirms whether the problem is in rendering or delivery.
Confirm the Redis caching layer is reachable
Start with the caching layer, because alerts and reports, async queries and dashboard thumbnails depend on it in most installations. From the Superset host or container, confirm the Redis instance named in your cache and Celery settings accepts connections from the web and worker processes, and that the network path and credentials match what Superset is configured to use. Done means a connection test succeeds from each tier. A failure here points to networking, DNS, authentication or a Redis instance that is down, and no report will run until it is fixed.
Verify the Celery beat schedule is running
Next, confirm that the Celery beat process is alive and writing schedule activity. Beat is the component that decides when a scheduled report should be queued, so a stopped beat process produces reports that never start, while workers and Redis look healthy. Check the process supervisor or container status for the beat service, and review its startup output for errors about the schedule or broker. Done means beat is running continuously and the report schedule is present in your configuration. If beat is missing, the fault sits in deployment or process management rather than in the report definition.
Check workers consume the alerts and reports queue
Confirm that at least one Celery worker is subscribed to the queue that carries alerts and reports tasks. A worker can be running and still ignore this queue if its startup command or configuration limits which queues it listens to, so the worker's queue subscription is the item to verify. Done means the worker reports the alerts and reports queue among the queues it consumes, and that queued tasks are picked up rather than accumulating. If tasks wait without starting, the worker configuration or the broker connection is the likely cause.
Review the report execution log
Once the queue is being consumed, read the execution record for the failed report. Superset records each run, including its state and any error message, so you can see whether the task started, which step it reached and how it ended. Look for states that show the task was queued but never finished, and for errors that name a timeout or an unreachable destination. Done means you know the last step that completed. Use that step to decide between a rendering problem and a delivery problem in the next two checks.
Inspect the screenshot rendering step
If the run reached rendering, check the headless browser step that captures the dashboard or chart image. Reports that fail here usually point to Playwright or Chromium missing from the image, a browser that cannot start under the executor user, or a page that loads too slowly for the configured timeout. Confirm the browser binary exists in the running image and that the worker can execute it as its configured user. Done means a rendering test completes for a small chart. A failure at this step points to the image contents, file permissions or timeout settings, not to SMTP or Slack.
Confirm delivery to email or Slack
Last, confirm the delivery channel. For email, check the SMTP host, port, authentication and sender address against your mail relay's requirements. For Slack, confirm the app has the scopes its delivery path needs. Superset 4.1.0 moved Slack delivery to Slack's file upload API, which requires the channels:read scope, and deprecated the original Slack integration, so an older app configuration can fail even when everything upstream works. Done means a test delivery reaches the recipient. A failure here means the rendered output existed but could not leave the platform.
Common causes: beat, workers, Chromium, executor user and dry-run mode
Most missing or failing Superset reports trace back to a small set of causes. Each one fails in a different place: the scheduler, the worker, the rendering browser, the account that runs the job, or a setting that suppresses delivery. Check them in that order so you do not chase a symptom in the wrong tier.
Celery beat not scheduling
Beat is the process that decides when a report or alert is due and queues the job. If beat is not running, no scheduled job is ever queued, so the report log shows nothing new for the schedule. Confirm that the beat process is deployed as its own container or service, that it runs in the same Superset codebase and configuration as the web tier, and that only one beat instance is active. Check its logs for startup errors before looking at workers.
Workers not started or on the wrong broker
Workers consume the queued jobs and execute them. A worker that is down, or that points at a different Redis or broker URL than the web tier and beat, will leave jobs sitting in a queue nobody reads. Confirm the worker process is running, that its broker and result backend settings match the other components, and that it listens on the queues Superset uses for reports. Compare the broker URL in each container, because a copied value with a different database index is a common cause.
Playwright or Chromium missing from the image
Scheduled reports with screenshots render the dashboard in a headless browser on the worker. If Playwright or Chromium is not installed in the worker image, or its system libraries are missing, the job fails at the rendering step while scheduling still looks healthy. Confirm the browser binary exists inside the running worker container, not only on the host, and that the image was rebuilt after any base image change. Worker logs usually name the missing library or executable.
Executor user without dashboard access
Each report or alert runs as a configured executor account. That account needs permission to open the dashboard or chart, and to read the underlying database through its role and any row level security filters. A report can fail or render an empty or partial page when the executor lacks access. Confirm which user is set as the executor, that the user holds the roles covering the dashboard, and that the same user can open the dashboard in a fresh browser session.
Dry-run mode left on
Alert and report settings include a dry-run switch that logs what would be sent without delivering it. Teams often enable it during testing and forget to disable it, so the schedule runs, the log shows success, and no email or Slack message leaves the system. Confirm the dry-run setting in the global configuration and in the feature flags for the environment you are testing, and confirm that the production configuration does not inherit a test value.
Screenshot timeouts on large dashboards
Rendering a dashboard with many charts or heavy queries can exceed the time the worker allows for screenshot capture, so the job ends with a timeout even though the dashboard works in a browser. Confirm the rendering timeout and the worker task time limits, check how long the charts take to load under the executor account, and look for slow warehouse queries. Reducing chart count in the report, or fixing the slowest queries, usually helps more than raising limits alone.
Email over SMTP versus Slack delivery
Email is the channel most organizations start with because it needs no third-party app approval. Superset hands the rendered report to an SMTP relay configured in your Superset settings, so the failure points sit mostly outside Superset: the network path to the relay, the credentials the relay accepts, and the sender address the relay allows. Those three items belong to your mail team, and they should confirm them before anyone debugs the Superset side.
- Relay reachability: Confirm that the Superset worker container, not only the web container, can open a connection to the relay host and port. Workers often run in a different subnet or namespace.
- Authentication: Ask the mail team which account and method the relay expects, and whether the account is allowed to send from a service context. Rotated or expired service credentials are a common cause of silent failures.
- Sender policy: Confirm that the configured sender address is permitted for the relay and that the domain's sender policy records include the relay. Messages can be accepted by the relay and then dropped or quarantined downstream.
- Attachment and size limits: Ask whether the relay caps message or attachment size, since large dashboard exports can exceed limits that small test emails never reach.
- Logging access: Agree in advance who can read relay logs for the Superset sender, so that delivery questions can be traced from a timestamp.
Before closing the ticket, send a test report to an internal mailbox from a worker and confirm both the relay log entry and the received message.
Slack delivery changed in Superset 4.1.0, which moved report delivery to Slack's newer file upload API and deprecated the original Slack integration. The new path requires the channels:read scope on the Slack app, so an app created for an older Superset release may deliver nothing after an upgrade. The failure often looks like a bot that cannot find or post to a channel, not like a configuration error, so teams tend to check the wrong thing first.
- Scope check: Review the OAuth scopes on the existing Slack app and confirm that
channels:readis present. Adding a scope usually requires reinstalling the app to the workspace so the new token is issued. - Deprecated integration: Identify whether your deployment still uses the original Slack integration. Plan the move to the current delivery path as a configuration change with a test, rather than waiting for the old path to fail.
- Channel membership: Confirm that the bot is a member of each target channel. Being installed in the workspace does not grant access to private channels.
- Token handling: Store the bot token in your secrets mechanism and record which person or team owns the Slack app, since app reinstalls and token rotations are typically done by workspace administrators.
- Workspace policy: Ask the Slack workspace administrators whether app installation requires approval, because a pending approval can look like a Superset fault.
After any upgrade to 4.1.0 or later, send a test alert to a private test channel and confirm the file arrives, not only that the job reports success.
The right channel depends on who must receive the report and what your governance rules allow. Email reaches people outside the chat workspace and fits recipients who never open Slack, while Slack suits team channels that already receive operational notifications. Neither channel removes the need for the Celery worker, the rendering stack, or the executor user, because a report is created before any channel receives it. Treat channel choice as a decision about recipients and approvals, and keep both paths tested if reports matter to several audiences.
- Recipient reach: Decide whether recipients are internal staff, external partners or a mix, since external recipients usually need email.
- Approval path: Ask whether mail relay changes or Slack app installation need a security review, and start that review early.
- Data handling: Confirm with your security team whether the report content, including data in screenshots, may leave the relay or the Slack workspace under your data classification.
- Ownership: Name the team that owns each channel's credentials and on-call contact, so a failure reaches someone who can act on it.
- Fallback: Decide whether a second channel is acceptable for critical reports, and document how recipients are told when one channel is down.
Record the chosen channel and its owners in your runbook so that the next troubleshooting session starts from the right team.
Configuration settings to check and when each fits
This table lists the settings a troubleshooting engineer reviews when reports fail, with the symptom that points to each one and what to confirm in the configuration documentation. Work down the rows in order, since a broken caching or broker layer often hides problems further down the list.
| Setting area | When it is the cause | What to confirm |
|---|---|---|
| Caching layer and Celery broker | Scheduled reports never start, or the queue shows jobs that stay pending. The architecture documentation ties alerts, reports and thumbnails to the caching layer and workers. | Confirm the cache and broker endpoints are reachable from both the web container and the worker container, and that both point to the same broker. |
| Celery worker process | Reports are queued but never executed, or they fail after a long wait. Scheduled jobs do not run when no worker consumes the queue. | Confirm a worker process is running, subscribed to the reports queue, and able to reach the metadata database and the data sources. |
| Celery beat process | Reports never fire on their schedule even though manual runs work. Beat is the scheduler, so a missing beat process stops all scheduled runs. | Confirm a single beat process is running, that its schedule store is writable, and that it is not duplicated across replicas. |
| Feature flags and dry-run behavior | A report appears to run but sends nothing, or alert logic runs without delivery. Dry-run style behavior hides delivery problems. | Confirm the alerts and reports feature flag is enabled and whether the report or alert is set to a test or dry-run mode in its settings. |
| Executor selection | The report runs under an unexpected user, so the data returned is missing rows or access is denied. Row-level and role rules then differ from what the owner sees. | Confirm which executor user the report is configured to run as and that this account has the dataset access the report needs. |
| Browser and screenshot settings | Screenshot-based reports fail or show blank charts. Playwright and Chromium must exist inside the image, and large dashboards can exceed timeouts. | Confirm the browser binary is present in the worker image and check the configured timeouts against the dashboard size and query time. |
| SMTP settings | Email reports fail with connection or authentication errors, or the message is accepted but never reaches the inbox. Most email failures trace to host, port, TLS or credential mismatch. | Confirm the SMTP host, port, encryption mode and sender address with the mail team, and test a direct send from the worker container. |
| Slack settings | Slack reports fail after upgrading to Superset 4.1.0 or later, which moved delivery to Slack's new file upload API. Older integrations deprecated in that release may still be configured. | Confirm the Slack app has the channels:read scope, that the bot is invited to the target channel, and that the configuration matches the UPDATING notes for your version. |
Questions teams ask before fixing report delivery themselves
How long does a typical fix for Superset alerts and reports take?
No duration is supplied for this work, so the honest answer depends on what is broken. A missing Celery beat schedule or a worker that never picked up a task is usually quicker to diagnose than a Chromium rendering failure or an SMTP relay that rejects the sender. The main drivers are how many layers are involved (web app, metadata database, Redis broker, Celery worker, beat, headless browser, mail or Slack), whether logs are retained and reachable, and whether a staging copy exists for safe testing. Ask any partner to state the diagnostic steps, the environments they will touch and the point at which they will report findings in writing before a timeline is agreed.
Can our in-house team fix report delivery without a partner?
Often yes, if the team already runs Superset in production and can read Celery and web server logs. Reports depend on the caching layer and worker components, and most installations use Redis and Celery for them, so the team needs working knowledge of those pieces alongside the Superset configuration. Teams without that experience usually lose time to the same few checks: whether the beat and worker processes run as the expected user, whether the headless browser can start inside the container image, and whether the mail or Slack credentials have the scopes the current release requires. An internal team can work through these checklists, and a partner is most useful when the cause is not obvious from the logs.
What access and help do we need to provide during troubleshooting?
Plan to provide access to the host or cluster where Superset runs, including the web, worker and beat containers or processes, and read access to their logs. You will also need the Superset configuration file and environment variables with secrets masked, the metadata database connection details for read-only inspection, and a named contact who can confirm the expected recipients and schedules. Mail administrators must be available to check the SMTP relay, sender authentication and any allow lists. Slack workspace administrators must confirm the app is installed, the bot has the scopes it needs, and the target channels are reachable. Agree in writing how credentials are shared and rotated afterward.
What does a fixed-scope troubleshooting engagement include?
A fixed-scope engagement is agreed in writing before work starts, and it should name the reports and dashboards in scope, the delivery channels (email, Slack or both), the environments covered and the deliverables. Typical items include a review of the Celery worker and beat setup, a check of the headless browser and its dependencies in the image, a dry-run test of a representative report, verification of SMTP or Slack settings, and a written summary of root causes with the changes made. Ask whether the scope covers fixes in production, changes in staging only, or a handover of recommended changes for your team to apply, and whether retesting after the fix is included.
Do we need to upgrade Superset to fix report delivery?
Not necessarily. Many delivery failures come from configuration, worker health, mail or Slack credentials, or the container image, and none of these require a new release. An upgrade becomes relevant when the installed version has a known defect that the project has fixed, or when the Slack integration in use is one the project has deprecated. Superset 4.1.0 moved Slack delivery to Slack's new file upload API, requiring the channels:read scope, and deprecated the original Slack integration, so an older Slack setup may need changes regardless of the fault. Before any upgrade, the Superset upgrade documentation calls for a metadata database backup, running superset db upgrade and superset init, testing in staging first, and checking UPDATING.md for breaking changes.
What does the cost of this work depend on?
Cost follows the written scope, and DeployOpen does not publish a price list. The main drivers are the number of delivery channels and reports involved, how many environments must be inspected, how much of the stack is in scope (Superset alone, or also the Redis broker, the mail relay, the Slack app or the container image), the state of logs and documentation, and whether a retest or handover is included. One-time work covers diagnosis and repair. Recurring costs, if any, depend on whether you want ongoing support or upgrade work under a retainer. Ask for a quote that lists each component, its deliverables and any assumptions about access.
Will troubleshooting expose our data or change access controls?
It can, so the scope should say how it is handled. Reports render dashboards and send their contents to recipients, so troubleshooting may involve viewing report payloads, mail queues or Slack messages that contain business data. Ask for a clear rule on what is read, what is copied out of your environment and how temporary test recipients are removed. Confirm that changes to roles, data access or the secret key are either out of scope or approved separately, and that every change is recorded so your team can review it afterward.
Security points when fixing report delivery
Fixing report delivery usually means touching the components that hold the most sensitive settings: the secret key, the service account that renders dashboards, the mail and chat credentials, and the headless browser. Each card below is a point to check in your own environment before you consider the fix finished.
Keep SECRET_KEY identical across containers
Superset uses SECRET_KEY to encrypt sensitive values stored in the metadata database, including database connection credentials. The web containers and the Celery worker and beat containers must load the same value, or the worker cannot read the settings it needs to deliver a report. Check that every container gets the key from the same secret source, and that the key is set explicitly rather than left at a default. Rotation is handled with PREVIOUS_SECRET_KEY, so plan it as a deliberate change, not a side effect of a redeploy.
Scope the executor user's access
Reports run as an executor user, and that account opens each dashboard in the headless browser to produce a screenshot or PDF. Any data that account can see ends up in the report, so it should hold only the dashboard and chart access the report needs. Use a dedicated account with read-only roles, confirm it cannot reach dashboards beyond the recipients' intended scope, and review it whenever report ownership changes.
Store SMTP and Slack credentials as secrets
SMTP passwords and Slack tokens belong in your secrets manager or orchestrator secret store, injected at runtime into the web and worker containers. They should not appear in superset_config.py, image layers, Git history or the report configuration fields visible to report owners. For Slack, the token needs only the scopes the delivery method requires, and rotating it should be a tested procedure that does not require editing configuration by hand.
Isolate the rendering browser
The headless Chromium that renders reports loads dashboard pages, and those pages can include links, filters and chart content shaped by users. Run the worker in a container with no direct access to internal metadata services, cloud instance endpoints or the secret store, and restrict its outbound network to the Superset web endpoint and the data sources it needs. Confirm which URLs the renderer can reach before you widen any network policy to make a failing report succeed.
When a fixed-scope troubleshooting engagement makes sense
Internal staff can usually fix a missing report on their own when the failure is isolated, reproducible and visible in the logs of one component. A single job that fails once after a configuration change, a Slack message that stops after a scope change, or a dashboard that times out only for one user are typically within reach of the team that already runs Superset. A fixed-scope review becomes worth considering when the same class of failure returns after each upgrade, when the Celery worker, beat process, Redis broker and Playwright browser cannot be observed from inside a restricted network, or when the team cannot see executor logs at all. In those cases the cost is often the time spent guessing across layers, and an outside reviewer can narrow the search faster.
Before asking for a quote, decide which questions the review must answer. Scope the review to a named set of reports, a named Superset version and a named environment, and agree on whether the work includes changes to the image or only diagnosis. Ask the provider to state in writing what they will need from you: read access to Superset logs, a staging instance that mirrors production, the SECRET_KEY handling process, SMTP or Slack credentials for a test recipient, and a named contact who can approve a restart. Ask how any change will be tested against the same report schedule that failed, and whether the review will include the dry-run mode check described earlier.
Expect written deliverables that a reader can keep and check later. A root-cause note should identify the failing component, the evidence for it (log excerpts, configuration values and versions, with secrets removed), the reason the failure occurred, and the change that addresses it. A verified test report should record each affected report type, the delivery channel, the recipient, the timestamp of the run and the result, including screenshots where the report depends on rendering. Request a list of open risks and any configuration left unchanged on purpose. No engagement can promise that every future report will deliver, so ask the provider to define what verification covers and what it does not.
How DeployOpen scopes and supports Superset report fixes
DeployOpen approaches alerts and report troubleshooting as a bounded engineering task inside your own infrastructure. We start from the written scope, reproduce the failing delivery path end to end, and fix it in the components that actually break, then hand over the evidence and runbooks your team needs to keep reports arriving.
How we scope
- The written scope lists which alerts and scheduled reports are affected and which delivery channels, email or Slack, must be fixed.
- Scope records the Superset version, metadata database, cache and worker topology, and where the image is built and run.
- Engagements are fixed-scope, so scope, deliverables and timelines are agreed in writing before any troubleshooting starts.
How we build
- We trace each failing report through beat scheduling, worker execution, screenshot rendering and delivery, and record where it stops.
- Fixes cover Celery beat and worker configuration, Chromium and Playwright in the image, executor user permissions and timeout settings.
- We verify each fix with dry-run mode and controlled test sends to your SMTP relay or Slack workspace before any recipient list is restored.
How we hand over
- You receive a written record of each root cause, the configuration or image changes made, and the test results behind them.
- Runbooks cover checking beat and worker health, reading report logs, rotating Slack or SMTP credentials and re-running a failed report.
- Your team walks through the handover with us so the people who run Superset can repeat the checks without us.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, including re-checks after Superset version upgrades.
- Support can cover reviewing report failures after changes to dashboard size, data volume or the Slack and SMTP configuration.
- Retainer scope, response expectations and review cadence are written down in the agreement, so you know what is covered before you need it.
