# Apache Superset Problems & Issues 2026 - Setup, Upgrades & Errors

Source: https://www.tryorbye.com/products/apache-superset
Last analyzed: 2026-11-16
Try or Bye score: 64/100

## Verdict: Try with caution

Apache Superset works for some teams, but users report recurring problems (score 64/100). Most reported issues: Is Apache Superset hard to set up?; Superset is too hard for business users; Superset upgrade broke my dashboards. Not a good fit for: Business users without SQL; Small teams with no DevOps; Excel-heavy finance teams. Users most often switch to Metabase, Microsoft Power BI, Tableau.

## What it is

Apache Superset is an open-source business intelligence platform from the Apache Software Foundation for exploring data, writing SQL in SQL Lab and building dashboards on top of SQL databases and warehouses. It is free to self-host (Docker, Kubernetes, pip) and is also sold as a managed cloud service by Preset. It suits data teams comfortable with SQL and Python ops more than business users who want a no-setup tool.

## Common errors & fixes

### Superset Alerts and Reports Not Sending Emails

Superset reports usually fail silently because the ALERT_REPORTS flag, Celery beat schedule, headless browser or SMTP is not set up, or dry-run mode is still on. Check the worker logs first.

1. **Enable the feature and scheduler** — Add 'ALERT_REPORTS': True to FEATURE_FLAGS Add reports.scheduler to CeleryConfig.beat_schedule (every minute) Run exactly one celery beat and at least one celery worker
2. **Turn off dry run** — Set ALERT_REPORTS_NOTIFICATION_DRY_RUN = False Restart the worker and beat
3. **Point the worker at Superset** — Set WEBDRIVER_BASEURL to the internal URL (e.g. http://superset:8088 in Docker, not localhost) Set WEBDRIVER_BASEURL_USER_FRIENDLY to the public URL curl the report URL from the worker container to test
4. **Fix screenshots** — Use the default image, not -lean or -dev, so Playwright and Chromium are included Look for 'Playwright is required' or 'Failed to launch the headless browser' in logs
5. **Test SMTP** — Set SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_MAIL_FROM Send a test email from a Python shell in the worker A 'Connection timed out' usually means the host blocks the SMTP port

Full guide: https://www.tryorbye.com/products/apache-superset/issues/alerts-reports-not-sending

### Superset Could Not Load Database Driver

'Could not load database driver' means the Python driver for that database is not installed in the Superset environment. In Docker, add it to docker/requirements-local.txt and rebuild, rather than pip installing into a running container.

1. **Add the driver in Docker** — Add the package to ./docker/requirements-local.txt Run docker compose build --force-rm Run docker compose up
2. **Install in a custom image** — Create a Dockerfile FROM apache/superset:<version> Run pip install <driver> in it Deploy that image instead of the stock one
3. **Verify the install** — docker exec into the container Run pip freeze | grep <driver>
4. **Pin compatible versions** — Check the driver's supported SQLAlchemy version Pin the driver version in requirements-local.txt if the latest conflicts

Full guide: https://www.tryorbye.com/products/apache-superset/issues/could-not-load-database-driver

### Superset CSRF Session Token Is Missing Error

'The CSRF session token is missing' means a POST request reached Superset without a valid session and X-CSRFToken header. For API scripts, keep one session, fetch /api/v1/security/csrf_token/ after login and send it as X-CSRFToken.

1. **Use a persistent session in scripts** — Create one HTTP session object (e.g. requests.Session() in Python) POST to /api/v1/security/login with the same session Reuse that session for every following call
2. **Fetch and send the CSRF token** — After login, GET /api/v1/security/csrf_token/ with the access token Read the result value Send it in the X-CSRFToken header and include a Referer header on POST/PUT/DELETE requests
3. **Exempt trusted API endpoints** — In superset_config.py add the endpoint to WTF_CSRF_EXEMPT_LIST Restart Superset Only do this for endpoints called by trusted backend services
4. **Fix cookies for iframes** — Set SESSION_COOKIE_SAMESITE = "None" and SESSION_COOKIE_SECURE = True Serve Superset over HTTPS Prefer the Embedded SDK with guest tokens instead of a plain iframe

Full guide: https://www.tryorbye.com/products/apache-superset/issues/csrf-session-token-missing

### Superset CSV Upload Option Missing

Superset only shows CSV/Excel upload for databases with 'Allow file uploads to database' enabled, and a known bug hid that checkbox when creating a new connection. Save the connection first, then edit it to enable uploads.

1. **Enable uploads on the connection** — Go to Settings > Database Connections Edit the database (not create) Open Advanced > Security and check 'Allow file uploads to database' Save
2. **Set an allowed schema** — In the same Security section, list the schemas uploads may write to if your version asks for it
3. **On Preset** — Edit the connection and tick 'Allow data upload' Older workspaces (before April 2023) need a database connection before CSV upload works

Full guide: https://www.tryorbye.com/products/apache-superset/issues/csv-upload-option-missing

### Superset Dashboard Showing Old Data (Not Refreshing)

Superset serves cached results until the cache timeout ends, so new data does not show up right away. Use Force refresh from the dashboard menu and lower the cache timeouts for that dataset or chart.

1. **Force refresh** — Open the dashboard Click ... > Force refresh dashboard
2. **Lower cache timeouts** — Edit the dataset > Settings > Cache timeout (or the chart's Cache timeout) Or lower CACHE_DEFAULT_TIMEOUT in DATA_CACHE_CONFIG Restart if you changed config
3. **Set auto-refresh** — Dashboard ... > Set auto-refresh interval Pick an interval matching how often data loads

Full guide: https://www.tryorbye.com/products/apache-superset/issues/dashboard-not-refreshing

### Superset Dashboard Slow or Charts Timing Out

Superset charts time out when a query runs longer than the 60-second client timeout or the proxy/WSGI timeout. Speed up or cache the queries, then raise SUPERSET_WEBSERVER_TIMEOUT together with your proxy and Gunicorn timeouts.

1. **Find the slow query** — Open the chart, click ... > View query Run it in SQL Lab or directly on the database If it is slow there too, add indexes, filters or a pre-aggregated table
2. **Turn on caching** — Configure DATA_CACHE_CONFIG with Redis in superset_config.py Set CACHE_DEFAULT_TIMEOUT Optionally set cache timeouts per dataset or per chart
3. **Raise timeouts at every layer** — Set SUPERSET_WEBSERVER_TIMEOUT (e.g. 300) in superset_config.py Raise nginx proxy_read_timeout and proxy_connect_timeout to at least the same value Keep the Gunicorn/WSGI timeout less than or equal to SUPERSET_WEBSERVER_TIMEOUT Restart all services
4. **Split heavy dashboards** — Move rarely used charts to a second dashboard or tab Use native filters with defaults that narrow the date range

Full guide: https://www.tryorbye.com/products/apache-superset/issues/dashboard-slow-timeout

### Superset Dashboards Broken After Upgrade

Most post-upgrade breakage comes from metadata migrations that did not run or ran with a different config. Back up the metadata database, run superset db upgrade and superset init with the service's config, then restart.

1. **Back up first** — Dump the metadata database (Postgres/MySQL) before any upgrade Export key dashboards as ZIP from the Dashboards list
2. **Run migrations correctly** — Check superset db current against the installed version Run superset db upgrade with the same config/environment as the service Run superset init Restart the web server and workers
3. **Read UPDATING.md** — Open UPDATING.md in the Superset repo for every version you skip Apply the listed config and feature flag changes
4. **Fix label collisions** — Open the failing chart in Explore Rename duplicate metric or column labels Save the chart

Full guide: https://www.tryorbye.com/products/apache-superset/issues/dashboards-broken-after-upgrade

### Superset Access Denied to Datasource for Users

Users see access-denied or 403 errors on charts when their role lacks datasource access to the datasets behind them. Database access does not cascade, so grant datasource access per dataset (or schema) to the role.

1. **Grant dataset access** — Go to Settings > List Roles Edit the role Add 'datasource access on [database].[dataset]' for every dataset the dashboard uses Or add schema access to cover a whole schema
2. **Use dashboard RBAC carefully** — With DASHBOARD_RBAC on, set Roles in the dashboard Properties Still confirm the role can read the underlying datasets
3. **Check 6.x API permissions** — If upgrading to 6.0 caused 403s, compare the role with Gamma Add missing read permissions such as can read on CurrentUserRestApi
4. **Point users to a request process** — Set PERMISSION_INSTRUCTIONS_LINK in superset_config.py so the denial message links to your access request page

Full guide: https://www.tryorbye.com/products/apache-superset/issues/datasource-access-denied

### Superset deck.gl Map Not Showing

A blank deck.gl or map chart usually means MAPBOX_API_KEY is missing or the Content Security Policy blocks Mapbox. Set the key, allow Mapbox hosts in Talisman, or switch the base map to OpenStreetMap.

1. **Set the Mapbox key** — Create a token at mapbox.com Set MAPBOX_API_KEY in superset_config.py or as an environment variable (docker/.env for Docker) Restart Superset
2. **Allow Mapbox in CSP** — Add https://api.mapbox.com and https://events.mapbox.com to connect-src in TALISMAN_CONFIG Reload and check the browser console for blocked requests
3. **Use OpenStreetMap tiles** — Configure DECKGL_BASE_MAP in superset_config.py with an OSM tile layer OSM tiles work without a key

Full guide: https://www.tryorbye.com/products/apache-superset/issues/deck-gl-map-not-showing

### Superset Docker Compose Not Starting (localhost:8088 Not Loading)

When Superset's Docker setup won't load, superset_init usually failed on the database, a port or networking, or you opened https instead of http. Read the init logs, free port 8088, then do a clean rebuild.

1. **Read the init logs** — Run docker compose logs superset_init Find the first error, not the last line
2. **Wait and use http** — Wait until init logs show all steps complete Open http://localhost:8088 (not https)
3. **Free the port** — Check what uses port 8088 (lsof -i :8088) Stop it or change the port mapping
4. **Clean rebuild** — Run docker compose down -v (this deletes local metadata) Run docker compose build --force-rm Run docker compose up

Full guide: https://www.tryorbye.com/products/apache-superset/issues/docker-compose-not-starting

### Superset Embedded Dashboard Not Loading (403 or Refused to Connect)

Embedded Superset dashboards fail when the EMBEDDED_SUPERSET flag is off, the host domain is not allowed, Talisman blocks framing, or the guest role lacks dataset access. Fix each layer in that order.

1. **Enable embedding** — Add 'EMBEDDED_SUPERSET': True to FEATURE_FLAGS Open the dashboard > ... > Embed dashboard Add your app's origin under Allowed Domains
2. **Allow framing** — In TALISMAN_CONFIG add your app origin to frame-ancestors Avoid disabling Talisman entirely in production
3. **Give the guest role access** — Set GUEST_ROLE_NAME to a role that has datasource access on every dataset the dashboard uses In 6.x, check API permissions such as can read on CurrentUserRestApi
4. **Refresh guest tokens** — Request tokens from your backend via /api/v1/security/guest_token/ Use fetchGuestToken in the SDK so it refreshes before GUEST_TOKEN_JWT_EXP_SECONDS
5. **Check server logs** — Guests only see a generic error; the real cause is in Superset logs

Full guide: https://www.tryorbye.com/products/apache-superset/issues/embedded-dashboard-not-loading

### Superset Refusing to Start Due to Insecure SECRET_KEY

Since 2.1, Superset will not start in non-debug mode with the default SECRET_KEY. Generate a random key (openssl rand -base64 42) and set it as SECRET_KEY in superset_config.py or the SUPERSET_SECRET_KEY environment variable.

1. **Generate and set a strong key** — Run openssl rand -base64 42 Add SECRET_KEY = '<value>' to superset_config.py, or export SUPERSET_SECRET_KEY=<value> Restart Superset
2. **Override the Docker default** — Set SUPERSET_SECRET_KEY in docker/.env-local or your compose environment Recreate the containers with docker compose up -d --force-recreate
3. **Rotate the key without losing connections** — Set PREVIOUS_SECRET_KEY to the old key and SECRET_KEY to the new one Run superset re_encrypt_secrets Remove PREVIOUS_SECRET_KEY afterwards
4. **Confirm the config is loaded** — Check SUPERSET_CONFIG_PATH points to your superset_config.py Run the CLI with the same environment as the web service

Full guide: https://www.tryorbye.com/products/apache-superset/issues/insecure-secret-key

### Superset Forgot Admin Password (How to Reset Login)

Superset has no built-in self-service password reset for database logins. Reset it on the server with superset fab reset-password, or create a new admin with superset fab create-admin.

1. **Reset the password from the CLI** — Open a shell on the server (docker exec -it superset_app bash for Docker) Run superset fab reset-password --username admin --password <new> Log in again
2. **Create a new admin** — Run superset fab create-admin Answer the prompts for username, name, email and password
3. **Check you hit the right database** — Run the command with the same SUPERSET_CONFIG_PATH and environment as the web app List users with superset fab list-users to confirm the username

Full guide: https://www.tryorbye.com/products/apache-superset/issues/reset-admin-password

### Superset SQL Lab Query Timeout

SQL Lab queries stop at the synchronous web timeout or at SQLLAB_ASYNC_TIME_LIMIT_SEC when run async. For long queries, enable async execution with Celery and a RESULTS_BACKEND, and raise the limits.

1. **Enable async queries** — Edit the database > Advanced > Performance and check 'Asynchronous query execution' Run Celery workers with the same config as the web app
2. **Configure a results backend** — Set RESULTS_BACKEND (e.g. RedisCache) in superset_config.py Restart the web app and workers
3. **Raise the limits** — Increase SQLLAB_ASYNC_TIME_LIMIT_SEC for async queries For sync queries align SUPERSET_WEBSERVER_TIMEOUT, Gunicorn and proxy timeouts
4. **Make the query lighter** — Add a LIMIT or narrower date filter Query a pre-aggregated table

Full guide: https://www.tryorbye.com/products/apache-superset/issues/sql-lab-query-timeout

## Common problems

- **Is Apache Superset hard to set up?** (onboarding): Installation is the most repeated complaint on Hacker News and in blog reviews: a production setup needs a metadata database, Redis, Celery workers, a secret key and a reverse proxy. Users report Docker init failures, Python version conflicts and a broken welcome screen on first run.
- **Superset is too hard for business users** (usability): G2 summaries, DashboardFox, Ksolves and Hacker News commenters all describe a steep learning curve, especially without SQL skills. Superset is seen as a tool engineers and analysts use to build reports, not one that non-technical staff explore on their own.
- **Superset upgrade broke my dashboards** (reliability): Upgrades are a recurring source of pain: GitHub discussions report broken dashboard styling and duplicate-label errors after moving from 4.x to 6.0, and an Open Food Facts incident report shows dashboards failing with missing-column errors when migrations did not run. One Hacker News user lost dashboards after an update.
- **Why is Superset so slow?** (performance): Slow dashboards and chart timeouts show up in G2 cons, Hacker News and many GitHub threads. The default client-side chart timeout is 60 seconds, and slow source queries, missing caching and proxy timeouts produce 504 errors on big dashboards.
- **Superset permissions are confusing** (security): Granting access is hard to manage: database access does not cascade to datasets, Gamma users need dataset access per table, and 6.0 tightened checks that caused new 403 errors. DashboardFox and several GitHub issues say it is hard to see who has which permission.
- **Superset embedded dashboard not working** (integrations): Embedding with guest tokens needs a feature flag, allowed domains, Talisman/CSP changes and correct guest role permissions. GitHub and forum threads are full of 403 errors, 'refused to connect' iframes and CSRF token errors when embedding.
- **Superset documentation is outdated and sparse** (support): Hacker News users say the docs are thin and that renamed concepts left online guides out of date; ToolRadar also lists documentation gaps. Many fixes live only in GitHub issues and discussions, often answered by a bot.
- **Superset default SECRET_KEY vulnerability** (security): In 2023 researchers found thousands of Superset servers still using the default SECRET_KEY, letting attackers forge sessions (CVE-2023-27524). Since 2.1 Superset refuses to start with the default key, which now trips up many first-time installs.
- **No official support for self-hosted Superset** (support): Self-hosted Superset has community support only (GitHub, Slack). Reviews say there is no fast, real-time help unless you pay Preset for its managed service, where standard support starts on the Professional plan.
- **Is Apache Superset really free?** (pricing): The software is free under the Apache 2.0 license, but reviewers point out that servers and developer time to run, secure and upgrade it add up. The managed alternative, Preset, charges $20-25 per user per month and $500 per month for 50 embedded viewers.
- **Superset has no real semantic layer or easy joins** (customization): Hacker News users note that joins across databases are limited and that there is no built-in semantic layer, so teams add dbt, Cube or Trino. Metabase is often recommended for teams that want joins without writing SQL.
- **Superset alerts and reports are hard to get working** (reliability): Scheduled email and Slack reports need Celery beat, workers, a headless browser and SMTP settings. The dev config sends nothing by default (dry run), and GitHub issues show reports silently failing when the worker cannot reach the webdriver URL.
- **Superset has lots of small UI bugs** (usability): Users list many papercuts: cryptic error messages, odd table behavior, things that cannot be copied, and dashboards that look different after upgrades. The 6.0 release reworked the visual design, which itself broke some existing layouts.

## What users like

- **Free and open source with no user limits**: Apache 2.0 licensed, so you can self-host for any number of users and dashboards without license fees, which is the main reason teams pick it over Tableau or Power BI.
- **Connects to almost any SQL database**: Works with Postgres, MySQL, ClickHouse, Druid, Trino, Snowflake, BigQuery and dozens more via SQLAlchemy drivers; Preset's comparison counts about 39 SQL engines versus 15 for Metabase.
- **Strong SQL Lab for analysts**: Hacker News and comparison articles praise SQL Lab and the control it gives SQL-heavy analysts compared with no-code BI tools.
- **Rich chart library including maps**: 40+ visualization types built on ECharts plus deck.gl geospatial charts, and dashboards can be styled with CSS.
- **Embeddable dashboards**: The Embedded SDK and guest tokens with row-level security let teams put dashboards inside their own apps; some users replaced Tableau this way.
- **Granular roles and row-level security**: Fine-grained role-based access and row-level security rules suit multi-team and multi-tenant setups once configured.

## Pricing

- **Self-hosted (Open Source)**: $0.00 (free) — hidden costs: Servers, Redis, metadata database and engineering time to install, secure and upgrade it
- **Preset Starter**: $0.00 (free) — hidden costs: Need to move to Professional for more than 5 users or any scheduled report
- **Preset Professional**: $25.00 (monthly) — hidden costs: Embedded dashboards need viewer licenses at $500/month for 50 viewers
- **Preset Professional (annual)**: $20.00 (yearly) — hidden costs: Embedded viewer licenses $500/month for 50 viewers
- **Preset Enterprise**: yearly — hidden costs: Custom quote; API access and embedding are add-ons

## Who should and shouldn't use it

- **Data engineers and SQL analysts** — Good fit: SQL Lab, wide database support and full control over the stack.
- **Startups avoiding BI license fees** — Good fit: No per-user cost if someone on the team can run Docker or Kubernetes.
- **SaaS teams embedding analytics** — Good fit: Embedded SDK with guest tokens and row-level security, free when self-hosted.
- **Teams on ClickHouse, Druid or Trino** — Good fit: Superset is well known for working with these engines.
- **Business users without SQL** — Avoid: Steep learning curve; Metabase or Power BI are easier for self-serve questions.
- **Small teams with no DevOps** — Avoid: Self-hosting, upgrades and security are on you; use Preset or a hosted tool instead.
- **Enterprises needing vendor support** — Depends: Fine via Preset Enterprise, but self-hosted has no SLA.
- **Excel-heavy finance teams** — Avoid: No spreadsheet-style modeling; Power BI fits better.

## Alternatives

- **Metabase** (https://www.tryorbye.com/products/metabase): The most recommended alternative: easier setup and a no-code query builder for non-technical teams, with joins built in. Trade-off: fewer database engines and less SQL-level control.
- **Microsoft Power BI** (https://www.tryorbye.com/products/power-bi): Polished Microsoft BI with Excel and Microsoft 365 integration and vendor support. Trade-off: per-user licenses and Windows-first desktop authoring.
- **Tableau** (https://www.tryorbye.com/products/tableau): Richer visual design and drag-and-drop analysis for business users. Trade-off: much higher per-user cost.
- **Looker Studio** (https://www.tryorbye.com/products/looker-studio): Free, nothing to host and easy for Google data sources. Trade-off: slow with big data and weak on non-Google sources.
- **Grafana**: Better for time-series and monitoring dashboards. Trade-off: weaker for general business analysis.
- **Redash**: Simple SQL-first dashboards. Trade-off: development has stalled since the Databricks acquisition.
- **Lightdash**: Open-source BI built on dbt models, so you get a semantic layer out of the box. Trade-off: requires dbt.

## FAQ

### Is Apache Superset worth it?

Yes, if your team writes SQL and can run Docker or Kubernetes: it is free, connects to almost any database and embeds well. If you need non-technical users to self-serve or have no one to maintain servers, Metabase, Power BI or Preset (hosted Superset) are usually less work.

### Is Apache Superset free?

The software is free and open source under the Apache 2.0 license with no user limits. You pay for servers and the engineering time to run it. Preset's hosted version is free for up to 5 users, then $20 per user per month billed annually ($25 monthly).

### What is the difference between Superset and Preset?

Apache Superset is the open-source project you self-host. Preset is a company that runs Superset as a managed cloud service with support, extra admin features and paid tiers. The core charts and SQL Lab are the same.

### Superset vs Metabase: which is better?

Metabase is easier for mixed-skill teams and faster to set up. Superset gives SQL analysts more control, more chart types and support for more database engines. Pick Metabase for self-serve business users, Superset for SQL-heavy data teams.

### Why is Apache Superset so hard to install?

A production install needs a metadata database, Redis, Celery workers, a secure SECRET_KEY, database drivers and often a reverse proxy. The Docker Compose setup is the easiest start; for production most teams use the Helm chart or Preset.

### Why is Superset so slow?

Most slowness comes from slow source queries, big dashboards firing many queries at once, missing caching or a 60-second client timeout lower than the query takes. Enable caching, pre-aggregate data and align SUPERSET_WEBSERVER_TIMEOUT with your proxy and WSGI timeouts.

### Does Apache Superset need SQL?

You can build charts in the Explore view without SQL once datasets exist, but creating datasets, virtual datasets and custom metrics usually needs SQL. Reviewers consistently say SQL knowledge makes Superset much easier.

### Can I embed Superset dashboards in my app?

Yes. Enable the EMBEDDED_SUPERSET feature flag, turn on embedding for the dashboard, set allowed domains, and have your backend request a guest token from /api/v1/security/guest_token/. Guest tokens expire after 5 minutes by default, so refresh them.

### How do I reset the Superset admin password?

Run superset fab reset-password --username admin --password <new> on the server (inside the container for Docker). If no admin exists, create one with superset fab create-admin.

### What is the latest version of Apache Superset?

Superset 6.1.0 was released on 13 May 2026. It added an extensions framework, an MCP service for AI assistants, dataset folders and reworked dashboard auto-refresh. 6.0 brought a visual redesign.

### Does Superset have support?

Self-hosted Superset has community support only (GitHub issues, discussions and Slack). Paid support comes from Preset, with standard support from the Professional plan and an SLA on Enterprise.

### Is Apache Superset secure?

It can be, but you must set a strong SECRET_KEY, keep up with releases and configure roles carefully. In 2023 thousands of servers were exposed because they kept the default key (CVE-2023-27524); Superset now refuses to start with it.

### Can Superset send scheduled email reports?

Yes, with the ALERT_REPORTS feature flag, Celery beat and workers, a headless Chromium (Playwright) and SMTP settings. On Preset, scheduled reports need the Professional plan.

---
Try or Bye aggregates problem patterns from user reviews, forums, and app stores. Methodology: https://www.tryorbye.com/methodology