Why Apache Superset queries time out and when to fix it
When a dashboard chart or a SQL Lab query fails with a timeout error, the instinct is to raise one number and retry. That rarely works, because timeouts are set at several layers and must be diagnosed layer by layer: the browser and reverse proxy, the Gunicorn web tier, the SQL Lab async path through Celery workers, the chart query timeout, and the limits enforced by the warehouse itself. Each layer can end the request on its own, and the error message often names only the layer that gave up last, not the one that caused the delay.
Apache Superset is an Apache Software Foundation project released under the Apache License 2.0, and it has no paid edition. The cost of fixing timeouts is therefore the configuration and architecture work itself: deciding which queries should run synchronously, which should move to asynchronous execution, and how the web tier, the Celery worker and the caching layer divide that work. The architecture documentation ties async queries to the caching layer and worker components, so a team without those components in place cannot simply switch long queries to async mode. Confirm which of them your deployment runs before changing any timeout value.
Teams need this page when timeouts appear for specific charts or queries, not for every slow page. Start by recording which layer reported the failure, the query text, and the datasource, then check whether the same query finishes in the warehouse console within a comparable time. If it does, the fix is in Superset or the proxy. If it does not, the fix belongs in the query design or the warehouse, and raising Superset's limits only moves the failure elsewhere.
How to tell which layer stopped the query
A timeout message in the browser rarely says which component gave up. Each layer between the user and the warehouse enforces its own clock, so the status code, the log line and the warehouse query history together point to the layer that stopped the work.
Reverse proxy and load balancer
The proxy in front of Superset enforces its own upstream timeout and returns the error to the browser while Superset may still be working. A 502 or 504 page that appears at a fixed elapsed time, while the Gunicorn log shows the request still in progress, points here. Check the proxy access and error logs for the upstream timeout, then compare the elapsed time against the timeout set on the proxy. Confirm the proxy timeout values in your own ingress or load balancer configuration.
Gunicorn worker timeout
Gunicorn kills a worker that does not respond within its timeout, and the request fails even though Superset did not finish. Look for a WORKER TIMEOUT line followed by a Worker exiting or Booting worker message in the web container logs, with the request path that was running. Repeated kills on chart or SQL endpoints mean the web tier is doing work that should be async or cached. Confirm the timeout and worker class in your configuration before changing anything.
SQL Lab async execution
When SQL Lab runs asynchronously, the browser polls for results while a Celery worker runs the query, so a timeout here shows as a query that never returns to the editor. Check the Celery worker logs for the task ID and any task revoke or time limit message, and confirm that the results backend and caching layer are reachable. A query marked as failed in SQL Lab's query history, with the worker log showing a time limit, is a worker-side limit rather than a browser problem.
Chart query timeout
A chart query can stop because Superset's own query timeout for the database connection ends the statement before the warehouse returns rows. The chart shows an error card while the warehouse may have completed the work. Compare the chart error text with the Superset query log entry for that request, and check the database connection's timeout setting in the connection configuration. Dashboards that fan out many charts at once make this layer fail more often than single charts.
Warehouse statement or job limits
The warehouse can cancel a statement on its own limit, such as a statement timeout, query queue rule or job runtime cap, even when Superset is still waiting. The warehouse query history shows these as cancelled or timed-out statements with a reason code, and the statement often keeps running after the client disconnects if no cancel is sent. Check the warehouse history for the statement text Superset sent, then compare the reason and runtime against the limits your administrators set for that account or role.
Timeout settings and when each one fits
This table compares the settings that cap a query at each layer, from the reverse proxy down to the warehouse. Read each row as a question: what stops the request, and is raising that limit fixing the cause or hiding it. Confirm exact keys and defaults for your Superset version in the configuration documentation before changing anything.
| Setting layer | What it controls | When raising it fits, and when it hides a problem |
|---|---|---|
| Proxy read timeout (Nginx, load balancer, ingress) | How long the proxy waits for Superset to return a response before closing the connection with a gateway error | Fits when a legitimate chart or export is slower than the proxy default and the query is already tuned. Hides a problem when dashboards are waiting on synchronous queries that should run async |
| Gunicorn worker timeout | How long a sync worker can stay silent before the master kills and restarts it, which cuts off the request | Fits only after the warehouse query is known to be bounded. Hides a problem when workers are exhausted by long queries, since each retry ties up another worker |
| SQL Lab async execution and Celery workers | Whether SQL Lab queries run on Celery workers and return results through the cache, so the browser does not hold a request open | Fits for long exploratory queries once workers and the results backend are sized. Hides a problem when queries that should be scheduled or pre-aggregated are run on demand by many users |
| Superset query timeout and row limits | The maximum time Superset allows a database query and the number of rows it returns to the browser | Fits when a dataset legitimately needs more rows or time for a known report. Hides a problem when charts pull raw detail that should be aggregated in the dataset |
| Warehouse statement timeout | The limit the database or warehouse enforces on a single statement, independent of Superset | Fits as the outer bound that protects cost and shared capacity. Hides a problem when raised to let unbounded scans finish, which moves the cost to the warehouse bill |
| Chart and dashboard cache timeout | How long a cached chart result is reused before the warehouse is queried again | Fits for data that changes on a known schedule. Hides a problem when a long cache masks a slow query that every cache miss still runs in full |
Fixing timeouts in the right order
This sequence isolates which layer ends a slow query, moves long work to async execution, and aligns timeouts from the inside out so each change is verified before the next one starts.
Capture the failing query and error
Ask the affected user for the dashboard or chart name, the time of the failure, and the exact error text shown in the browser. Pull the matching entries from the Superset application log and the proxy access log for the same minute, and copy the SQL that Superset generated for the chart from the query view. Done means you have one failing request with its timestamp, its error message, and the SQL that was sent to the warehouse, so you can reproduce it independently.
Confirm which layer ended the request
Compare the timestamps and error messages across layers. A 504 or a gateway message usually points to the proxy, a worker timeout in the Gunicorn log points to the web tier, a timeout message from the database driver points to the warehouse, and an async job that never returned points to Celery or the broker. Run the same SQL directly in the warehouse client with a known duration. If it finishes in the warehouse but not in Superset, the problem sits in the application stack. Done means you can name one layer as the first to end the request.
Move long-running queries to SQL Lab async
For queries that legitimately take longer than an interactive request should wait, enable asynchronous execution in SQL Lab. This requires the caching layer and Celery worker components described in the Superset architecture documentation, with Redis as the broker and result backend in most installations. Confirm that a worker consumes the query queue, then run a test query that exceeds the web request window and check that it completes and returns results through the async path. Done means a known long query finishes without holding the browser connection open.
Align proxy and Gunicorn timeouts
Set the timeouts so the outermost layer waits longer than the layers inside it. In practice, the warehouse statement limit and the Superset query timeout should expire before the Gunicorn worker timeout, and the Gunicorn timeout should expire before the reverse proxy or load balancer timeout. If the proxy cuts first, users see gateway errors while the worker is still running the query. Record every value you changed in a single table with the file or setting name. Done means each layer's timeout is documented and ordered from innermost to outermost.
Tune chart query limits and warehouse limits
Review the per-database query timeout in Superset and the row limits on charts and datasets, then adjust them for the slowest chart you reproduced. Where the warehouse supports it, set a statement timeout or equivalent limit for the Superset service account so runaway queries stop on the database side rather than only in the application. Confirm the setting names and behavior with your warehouse vendor and the Superset configuration documentation before changing them. Done means the warehouse stops the reproduced query at the intended limit and Superset reports that limit as the error, not a generic failure.
Retest in staging before production
Repeat the reproduction from the first step in a staging environment that matches production's proxy, Gunicorn, worker and warehouse settings. Run the slow chart synchronously, run the SQL Lab async query, and load the dashboard as a typical user would. Confirm that each fast query returns within its layer's limit and that each long query either completes asynchronously or fails with the intended error. Done means the staging results match your expectations, and the changes are ready to promote with the same configuration files.
Moving long queries to async execution with Celery
Async execution is the fix to reach for when a query is legitimately long and the timeout is at the web tier, because async queries move execution out of the web request and onto a worker. According to the Superset architecture documentation, async queries, alerts and reports, and dashboard thumbnails all require the caching layer and worker components, and most installations use Redis as the cache and broker and Celery for the workers. Before you change anything, confirm that the Celery worker and beat processes, the Redis instance and the async query settings in your configuration are all present and reachable from the web tier. Enabling the setting without a running worker will leave queries queued with no one to run them.
The trade-off is that async hides the web timeout but moves the cost somewhere else. The browser now polls for results, so users see a query that keeps running instead of an error, which is the right experience for a 20-minute extract but a poor one if the query should never have run that long. You take on worker capacity that has to be sized for peak concurrency, result storage that holds query output until users fetch it, and a queue that can back up when many people run heavy SQL at once. Ask the warehouse team how many concurrent queries the account allows, and decide which queries are allowed to run async before you widen the limits.
Plan the metadata database before the async rollout. Superset's architecture documentation says SQLite, the default in Quickstart and PyPI installs, is not recommended for production, and the Docker Compose PostgreSQL container is not recommended either, so use a PostgreSQL or MySQL instance you operate. Confirm your version against the supported list in the configuration documentation (PostgreSQL 10 to 17, MySQL 5.7 and 8.x) before you deploy. Then test one slow query end to end through a worker, check that results appear and expire as expected, and watch queue depth and worker memory for a full working day.
Security and operational risks of raising timeouts
Raising a timeout is a capacity and security decision, not only a usability fix. The cards below cover the risks that follow a longer limit, the controls that should bound it, and the checks to run before and after a change.
Long queries hold scarce capacity
A longer timeout lets a slow query keep a Gunicorn worker, a Celery worker and a warehouse slot for much longer. Several users refreshing the same heavy chart can then exhaust the pool and block everyone else, including people running short queries. Before raising a limit, confirm how many web workers and async workers are free at peak, and whether the warehouse account has a concurrency or queue limit that a stalled query would consume.
Database privileges are the real guardrail
Superset's timeout settings stop waiting, but they do not stop the database from finishing the query. The database role Superset connects with should define what a query can read and how long the warehouse will run it. Check statement timeouts and resource monitors on the warehouse side, and confirm that the connection user cannot reach tables outside the datasets it serves. Review SQL execution limits as part of the security hardening work, not as a separate tuning exercise.
Stable SECRET_KEY across replicas
Changing the web tier, such as adding replicas, moving to a new container image or switching the timeout behavior behind a proxy, can break sessions if replicas do not share the same SECRET_KEY. Superset requires a user-specified secret key to start, and supports rotation with PREVIOUS_SECRET_KEY. Confirm that every replica reads the same key from your secret store and that rotation is planned as its own change with a documented rollback.
Logging timed-out queries
A timeout that users see as a generic error leaves no trail for the operations team. Decide where Superset and the database record query text, user, dataset, duration and the error returned when a limit is hit, and who reviews those records. Without this, a longer timeout can hide a dashboard that repeatedly runs an expensive query, and an abusive pattern can look like ordinary load. Confirm that query text in logs is handled under your data-handling rules.
Patch before changing timeout behavior
Timeout handling in Superset has changed between releases, so a tuning change made on an old version may not behave the same after an upgrade. Patch to a supported release first, then change timeouts. The upgrade guide advises backing up the metadata database, running the upgrade steps, testing in staging first, and checking UPDATING.md for breaking changes. Record the version in use before and after each timeout change so that any regression can be traced.
Questions teams ask before fixing Superset timeouts
How long does it take to fix Superset query timeouts?
The duration depends mainly on how many layers are involved and how quickly you can reproduce the slow query. A timeout caused by one proxy setting is a short change plus verification. A timeout that spans the web tier, SQL Lab async execution, chart queries and a warehouse limit takes longer because each layer needs its own evidence and its own test. Ask any partner for a timeline built from a written scope, and expect it to name which layers are in scope, which staging environment will be used, and who signs off on production changes. No general figure applies across environments, so treat any single number you hear with caution.
Can our in-house team diagnose and fix Superset timeouts?
Often yes, if the team can read web server and proxy logs, has access to the Superset metadata for query history, and can run the same queries against the warehouse. The work becomes harder when it crosses ownership lines, such as a platform team that controls the ingress, a data team that owns the warehouse and an application team that manages Superset. Timeouts that come back after a fix usually point to a layer nobody measured. A partner adds most value when a fixed-scope review can cover all layers in one pass and produce a written record of what changed and why.
What access and information do we need to provide?
Expect to provide read access to web server, proxy and worker logs, the Superset configuration as deployed (with secrets removed), and the warehouse query history for the affected users and dashboards. A staging copy of Superset that connects to a representative database is important, because changing timeout values in production to test them creates risk. You will also need a named contact who can approve configuration changes and a window to restart components. Confirm with your security team what data may leave your environment before sharing any logs, since queries can contain sensitive identifiers.
What costs should we expect when fixing timeouts?
There are three main components. Internal time covers engineers reading logs, reproducing slow queries and reviewing changes. Infrastructure covers any added capacity for web workers, Celery workers and Redis if you move long queries to async execution, which is a recurring cost once those components run. Warehouse compute is the component most often overlooked, because a query that finally completes may scan the same data for longer and cost more on a consumption-priced platform. Ask for a quote that separates one-time implementation work from the recurring infrastructure and warehouse costs it will create.
Is raising the timeout ever the right fix?
Yes, when a query is legitimate, the warehouse is sized for it and users need the result, but the default limit sits below the normal runtime. Raising a timeout without checking the other layers is the common mistake. A longer web request keeps a Gunicorn worker occupied and can pile up requests behind a proxy, while a longer chart query keeps a database connection open on the warehouse. Before raising any value, confirm that the lower layers allow it, measure how many workers the change will tie up, and decide whether the query belongs in SQL Lab async execution instead of a synchronous request.
When should we bring in a partner to fix Superset timeouts?
Consider a partner when timeouts affect business users, span several teams, or return after each fix. A partner is also useful when you need a documented, repeatable configuration for staging and production, or when the warehouse team and the Superset team disagree about where the bottleneck sits. DeployOpen implements, configures, hardens and supports self-hosted open-source platforms in your own infrastructure, and most engagements are fixed-scope with scope and deliverables agreed in writing before work starts. Ongoing support is available as a retainer if timeouts recur as usage grows.
Official Superset documentation to read first
Start with the Superset architecture documentation before you touch any timeout setting. It explains the four components involved in a slow query path: the Flask and React application, the metadata database, the optional caching layer and the optional Celery worker and beat processes. Knowing which of these sits in the request path tells you which timeout you are actually hitting. A chart request that waits on the web tier fails differently from an async SQL Lab query that is queued to a worker, and the architecture page is the quickest place to map your symptoms onto those components. Read it against your own deployment diagram so you can name the layer that is timing out. Use the architecture documentation as the reference for component roles.
The configuration documentation is where the timeout-related keys are defined, and it is the page you will return to most often. Search it for the settings that govern web server, SQL Lab and chart query limits, then record the exact key names and default values that appear in the release you run. Do not copy keys from blog posts or older forum threads, because names and defaults change between versions. Confirm each setting in your own superset_config.py against the documentation for that release. The configuration documentation lists these options alongside the database and caching settings that interact with them.
Read the upgrade guide before you change versions as a fix for timeouts, since a newer release can alter query handling or configuration keys. The guide asks you to back up the metadata database, run superset db upgrade and superset init, test in staging and check UPDATING.md for breaking changes. Confirm the current release line with the upgrade documentation and the project's release list, and treat any timeout change as a configuration change to be tested in staging first.
How DeployOpen diagnoses and fixes Superset timeouts
DeployOpen approaches query timeouts as a layered problem, tracing each request from the browser through the proxy, web tier, SQL Lab and chart paths, and the warehouse. Engagements are fixed-scope, so the timeout layers, fixes and evidence are agreed in writing before any configuration changes begin.
How we scope
- Map which timeouts users actually hit: proxy, Gunicorn, SQL Lab async, chart queries or warehouse limits.
- Agree in writing which dashboards, databases and user groups are in scope for the fix.
- Define the test cases, reproduction steps and success evidence before the first change is made.
How we build
- Adjust proxy, web server and Superset timeout settings in your environment, one layer at a time.
- Move qualifying long-running queries to async execution and confirm workers pick them up.
- Test each change in staging against the reproduction cases, then record results before promotion.
How we hand over
- Document every timeout value changed, the reason for it, and the layer it belongs to.
- Provide a runbook that shows how to read timeout errors and which layer to check first.
- Walk through the configuration with your platform and data teams so they can maintain it.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Retained support can cover re-checking timeouts after Superset upgrades or warehouse changes.
- Confirm with us during scoping which support model fits your team and change process.
