# Apache Superset — User Guide

## 1. Quick Start

Apache Superset is a modern, enterprise-ready business intelligence web application. It provides an intuitive interface for data exploration and visualization, a feature-rich SQL editor (SQL Lab), and the ability to build interactive dashboards — all without writing code.

**Key features:**

- 40+ built-in visualization types (ECharts, deck.gl, D3, pivot tables, and more)
- SQL Lab — a full-featured SQL IDE with autocomplete, query history, and cost estimation
- Interactive dashboards with cross-filtering and native filter controls
- Connect to any SQL-speaking database (PostgreSQL, MySQL, BigQuery, Snowflake, Trino, and dozens more)
- Scheduled reports and alerts delivered via email or Slack
- Row-level security for multi-tenant data access
- Embedded dashboard SDK for integrating charts into external applications
- Tagging, annotation layers, and CSS template customization

**Prerequisites:** Docker and Docker Compose installed on your machine.

**Fastest path to a running instance:**

```bash
git clone https://github.com/apache/superset.git
cd superset
docker compose -f docker-compose-image-tag.yml up -d
```

```text
Creating network "superset_default" with the default driver
Creating superset_db_1     ... done
Creating superset_redis_1  ... done
Creating superset_app_1    ... done
Creating superset_worker_1 ... done
Creating superset_beat_1   ... done
```

Open `http://localhost:8088` in your browser. Log in with `admin` / `admin`.

> [!TIP]
> To load example dashboards and datasets on first launch, set `SUPERSET_LOAD_EXAMPLES=yes` in your environment before starting the containers.

**What to try next:**

- Create your first chart: navigate to **Charts > + Chart**, pick a dataset and visualization type
- Explore SQL Lab: click **SQL Lab > SQL Editor** and write a query against any connected database
- Build a dashboard: go to **Dashboards > + Dashboard** and drag charts onto the canvas
- See the Admin Guide for full configuration, deployment, and security guidance

---

## 2. Installation

### System Requirements

| Component | Minimum | Recommended |
|---|---|---|
| CPU | 2 cores | 4+ cores |
| Memory | 4 GB | 8+ GB |
| Disk | 10 GB | 40+ GB (for data caching) |
| Python | 3.9+ | 3.11+ |
| Node.js | 18+ | 20+ |
| Database | SQLite (dev only) | PostgreSQL 12+ |
| Cache/Queue | — | Redis 6+ |

> [!IMPORTANT]
> SQLite is supported only for local development and testing. Production deployments **must** use PostgreSQL or MySQL as the metadata database.

### Installation Methods

=== "Docker Compose (Recommended)"
    ```bash
    git clone https://github.com/apache/superset.git
    cd superset
    docker compose -f docker-compose-image-tag.yml up -d
    ```

    The compose file starts PostgreSQL, Redis, the Superset web app, a Celery worker, and a Celery beat scheduler.

=== "pip (PyPI)"
    ```bash
    pip install apache-superset
    superset db upgrade
    superset fab create-admin
    superset init
    superset run -p 8088 --with-threads --reload
    ```

=== "Helm (Kubernetes)"
    ```bash
    helm repo add superset https://apache.github.io/superset
    helm install my-superset superset/superset
    ```

    The Helm chart (v0.15.4, appVersion 5.0.0) bundles PostgreSQL and Redis as sub-charts from Bitnami.

=== "From Source"
    ```bash
    git clone https://github.com/apache/superset.git
    cd superset

    # Backend
    python -m venv venv && source venv/bin/activate
    pip install -e .

    # Frontend
    cd superset-frontend
    npm ci
    npm run build
    cd ..

    # Initialize
    superset db upgrade
    superset fab create-admin
    superset init
    superset run -p 8088 --with-threads --reload
    ```

### Post-Install Verification

```bash
curl http://localhost:8088/health
```

```text
OK
```

Additional health endpoints: `/healthcheck`, `/ping`, `/version`.

> [!WARNING]
> On first launch, change the default admin password immediately. The default credentials (`admin`/`admin`) are well-known and must not be used in any environment accessible outside localhost.

### Install Troubleshooting

### Error: `No module named 'superset'`

**Cause:** The package is not installed in the active Python environment.

**Solution:**
1. Activate your virtual environment: `source venv/bin/activate`
2. Install: `pip install apache-superset`

**Prevention:** Always work inside a virtual environment.

### Error: `sqlalchemy.exc.OperationalError: unable to open database file`

**Cause:** The metadata database path does not exist or lacks write permissions.

**Solution:**
1. Set `SUPERSET_HOME` to a writable directory
2. Or configure `SQLALCHEMY_DATABASE_URI` to point to PostgreSQL

**Prevention:** Use PostgreSQL for all non-trivial deployments.

### Error: Container fails with `FATAL: role "superset" does not exist`

**Cause:** The PostgreSQL container has not been initialized with the expected user.

**Solution:**
1. Remove existing volumes: `docker compose down -v`
2. Restart: `docker compose up -d`

**Prevention:** Do not reuse database volumes from incompatible Superset versions.

### Error: `Error: Could not locate a Flask application`

**Cause:** The `FLASK_APP` environment variable is not set.

**Solution:**
```bash
export FLASK_APP=superset
```

**Prevention:** Set this in your shell profile or `.env` file.

### Error: `Node.js version must be >= 18`

**Cause:** Frontend build requires Node.js 18+.

**Solution:**
```bash
nvm install 18
nvm use 18
```

**Prevention:** Use `nvm` or `fnm` to manage Node versions.

### Error: Helm upgrade fails — `psycopg2 is no longer bundled` (#31026)

**Cause:** Lean Superset Docker images removed `psycopg2` from the base image.

**Solution:**
1. Use the full image tag (not `-lean`)
2. Or add `psycopg2-binary` to your custom requirements

**Prevention:** Pin image tags and test upgrades in a staging namespace first. (Community issue #31026, 25 comments)

### Error: `SUPERSET_SECRET_KEY must be set`

**Cause:** Production mode requires an explicit secret key.

**Solution:**
```bash
export SUPERSET_SECRET_KEY=$(openssl rand -base64 42)
```

**Prevention:** Store the key in your `.env` file or Kubernetes Secret.

### Error: `Permission denied` when writing to `/app/superset_home`

**Cause:** Container user does not own the home directory.

**Solution:**
```bash
docker compose exec superset chown -R superset:superset /app/superset_home
```

**Prevention:** Set `runAsUser` in Helm values to match the volume owner.

### Error: Frontend build fails with `JavaScript heap out of memory`

**Cause:** Webpack requires significant memory for the build.

**Solution:**
```bash
export NODE_OPTIONS="--max-old-space-size=8192"
npm run build
```

**Prevention:** Allocate at least 8 GB to Node.js during builds.

### Error: `redis.exceptions.ConnectionError: Error connecting to redis`

**Cause:** Redis is not running or misconfigured.

**Solution:**
1. Verify Redis is accessible: `redis-cli ping`
2. Check `REDIS_HOST` and `REDIS_PORT` in your config

**Prevention:** Always start Redis before the Superset application.

---

## 3. Configuration

Superset configuration is done through a Python module. By default, Superset loads `superset.config`, but you can override this by setting the `SUPERSET_CONFIG` environment variable.

```bash
export SUPERSET_CONFIG=my_custom_config
```

### Essential Settings

| Setting | Purpose | Example |
|---|---|---|
| `SUPERSET_SECRET_KEY` | Cryptographic key for session cookies and CSRF | `openssl rand -base64 42` |
| `SQLALCHEMY_DATABASE_URI` | Metadata database connection | `postgresql+psycopg2://user:pass@host/superset` |
| `MAPBOX_API_KEY` | Enable Mapbox-based visualizations | Your Mapbox token |

### Common Environment Variables

| Variable | Default | Purpose |
|---|---|---|
| `SUPERSET_SECRET_KEY` | (none) | **Required** in production |
| `SUPERSET_CONFIG` | `superset.config` | Python module path for configuration |
| `SUPERSET_APP_ROOT` | `/` | Deploy under a URL subpath |
| `SUPERSET_ENV` | (none) | Environment identifier |
| `SUPERSET_LOG_LEVEL` | `INFO` | Logging verbosity |
| `FLASK_DEBUG` | (none) | Enable Flask debug mode |
| `MAPBOX_API_KEY` | (none) | Mapbox token for map visualizations |

> [!TIP]
> For the complete configuration reference including all feature flags, caching options, Celery settings, and security configuration, see the Admin Guide.

### Feature Flags

Superset uses feature flags to control optional functionality. Set them in your `superset_config.py`:

```python
FEATURE_FLAGS = {
    "ALERT_REPORTS": True,       # Enable scheduled reports and alerts
    "TAGGING_SYSTEM": True,      # Enable the tagging system
    "THUMBNAILS": True,          # Enable chart/dashboard thumbnails
    "DYNAMIC_PLUGINS": True,     # Enable the plugin manager
    "ENABLE_EXTENSIONS": True,   # Enable the extension system
}
```

### Database Connections

Add new database connections through the UI (**Settings > Database Connections > + Database**) or via the REST API. Superset supports 70+ database engines through SQLAlchemy. Common connection string formats:

| Database | URI Format |
|---|---|
| PostgreSQL | `postgresql+psycopg2://user:pass@host:5432/db` |
| MySQL | `mysql+mysqlconnector://user:pass@host:3306/db` |
| BigQuery | `bigquery://project` |
| Snowflake | `snowflake://user:pass@account/db/schema` |
| Trino | `trino://user@host:8080/catalog` |
| ClickHouse | `clickhousedb://user:pass@host:8123/db` |
| DuckDB | `duckdb:///path/to/file.db` |

> [!NOTE]
> Each database engine may require installing an additional Python driver package. The `superset/db_engine_specs/` directory contains 73 engine specification files covering supported databases, each with connection validation, time grain handling, and engine-specific query optimizations.

---

## 4. Core Usage

### Exploring Data with Charts

Superset's Explore view is the primary interface for building visualizations.

**Creating a new chart:**

1. Navigate to **Charts > + Chart**
2. Select a dataset (table/view from a connected database)
3. Choose a visualization type from the 40+ available options
4. Configure metrics (what to measure) and dimensions (how to group)
5. Adjust time range, filters, and display options
6. Click **Run** to preview
7. Click **Save** to persist the chart

**Visualization types include:**

| Category | Chart Types |
|---|---|
| Time Series | Line, Area, Bar, Scatter, Mixed Timeseries |
| Distribution | Histogram, Box Plot, Heatmap |
| Categorical | Bar, Pie/Donut, Sunburst, Treemap |
| Geographic | World Map, Country Map, deck.gl layers, Point Cluster Map, Cartodiagram |
| Tables | Table, Pivot Table, AG Grid Table |
| Relationships | Chord, Sankey, Parallel Coordinates |
| Other | Big Number, Word Cloud, Calendar Heatmap, Handlebars, Horizon, Rose, Partition |

**Chart controls and options:**

- **Metrics:** Aggregation functions (SUM, AVG, COUNT, etc.) or custom SQL expressions
- **Dimensions:** Columns to group by (categories, time columns)
- **Filters:** Ad-hoc WHERE clauses to slice data
- **Time grain:** Aggregation granularity (second, minute, hour, day, week, month, year)
- **Row limit:** Maximum rows returned (default: 50,000)
- **Advanced analytics:** Rolling window, time comparison, resample, and percentage calculations
- **Conditional formatting:** Apply color rules to table cells based on values
- **Annotation layers:** Overlay time-based events on timeseries charts
- **Cross-filtering:** Enable click-to-filter behavior in dashboards

> [!TIP]
> Use the **Time Comparison** feature on timeseries charts to compare current values against a prior period (day, week, month, or custom offset) directly within the chart.

**Result formats:**

Charts can output data in multiple formats:
- `JSON` — structured column-based results (default)
- `CSV` — comma-separated values for download
- `XLSX` — Excel spreadsheet format

### SQL Lab

SQL Lab is a full-featured SQL IDE built into Superset.

**Key capabilities:**

- Write and execute SQL queries against any connected database
- Autocomplete for table names, columns, and SQL keywords
- Query cost estimation (for supported databases) before executing
- Tab-based workspace — run multiple queries in parallel
- Export results as CSV or XLSX
- Save queries for reuse
- Create datasets directly from query results
- Jinja template support for parameterized queries
- SQL formatting with template variable interpolation

**Writing your first query:**

1. Go to **SQL Lab > SQL Editor**
2. Select a database and schema from the dropdowns
3. Write your SQL in the editor
4. Click **Run** (or press `Ctrl+Enter`)
5. View results in the table below
6. Optionally click **Save** to store the query

**Using Jinja templates in SQL:**

```sql
SELECT *
FROM orders
WHERE order_date >= '{{ from_dttm }}'
  AND order_date < '{{ to_dttm }}'
LIMIT {{ row_limit }}
```

**Query result types:**

| Result Type | Description |
|---|---|
| `COLUMNS` | Column metadata only |
| `FULL` | Complete result with metadata |
| `QUERY` | Generated SQL without execution |
| `RESULTS` | Data rows only |
| `SAMPLES` | Sample data preview |
| `TIMEGRAINS` | Available time granularities |
| `DRILL_DETAIL` | Drill-down detail rows |

**Query status tracking:**

| Status | Meaning |
|---|---|
| `PENDING` | Query queued for execution |
| `RUNNING` | Currently executing |
| `SUCCESS` | Completed successfully |
| `FAILED` | Execution error |
| `STOPPED` | Cancelled by user |
| `TIMED_OUT` | Exceeded time limit |
| `SCHEDULED` | Awaiting scheduled execution |

> [!WARNING]
> SQL Lab respects database-level permissions. Ensure your database connection has appropriate read/write access configured. DML operations (`INSERT`, `UPDATE`, `DELETE`) are only allowed when `allow_dml` is enabled on the database connection.

### Dashboards

Dashboards combine multiple charts into interactive views.

**Building a dashboard:**

1. Go to **Dashboards > + Dashboard**
2. Enter a title
3. Click **Edit** to enter edit mode
4. Drag charts from the chart panel onto the canvas
5. Resize and arrange charts using the grid layout
6. Add Markdown components for text, headers, or dividers
7. Add tabs to organize sections
8. Configure native filters for interactive filtering
9. Click **Save**

**Dashboard features:**

- **Cross-filtering:** Click on a chart element to filter all other charts on the same dataset
- **Native filters:** Add dropdown, range, or time filters that apply across charts
- **Permalinks:** Share specific dashboard states (filters, time ranges) via URL
- **Favorites:** Star dashboards for quick access
- **Thumbnails:** Auto-generated previews for dashboard listings
- **Copy:** Duplicate a dashboard with all its charts
- **PDF export:** Export dashboard snapshots as PDF
- **Chart customizations:** Per-dashboard chart display overrides
- **Color configuration:** Custom color schemes per dashboard
- **Tab support:** Organize charts into named tabs

> [!NOTE]
> Dashboard cross-filtering works across all charts that share the same dataset. Charts from different datasets will not respond to cross-filter selections.

### Reports and Alerts

When the `ALERT_REPORTS` feature flag is enabled, you can schedule automated report delivery and data-driven alerts.

**Creating a report:**

1. Go to **Settings > Alerts & Reports > + Report**
2. Select a dashboard or chart to report on
3. Configure the schedule using cron syntax (timezone-aware)
4. Add recipients (email addresses or Slack channels)
5. Choose the output format: PNG screenshot, PDF, or CSV data
6. Optionally set a grace period and timeout
7. Add a custom email subject and context markdown

**Creating an alert:**

1. Go to **Settings > Alerts & Reports > + Alert**
2. Write a SQL query that returns a value to evaluate
3. Configure the alert condition using the validator
4. Set the schedule for how often to check
5. Add notification recipients
6. Configure the validator type and threshold

> [!IMPORTANT]
> Reports and alerts require a running Celery worker and beat scheduler. The beat schedule fires the `reports.scheduler` task every minute and prunes logs daily at 00:10.

### Tags

When the `TAGGING_SYSTEM` feature flag is enabled, you can organize charts, dashboards, and datasets with custom tags.

**Tag operations:**

- Create, read, update, and delete tags
- Associate tags with charts, dashboards, and datasets
- Bulk-create tags with multi-object association
- Filter list views by tag
- Favorite tags for quick access
- View all objects tagged with a specific tag

### Annotations

Annotation layers allow you to overlay time-based events on timeseries charts:

1. Go to **Settings > Annotation Layers > + Annotation Layer**
2. Create a layer with a name and description
3. Add individual annotations with start/end dates and descriptions
4. Reference the layer in any timeseries chart's annotation configuration

### CSS Templates

CSS templates allow you to customize the appearance of dashboards:

1. Go to **Settings > CSS Templates**
2. Create a template with custom CSS
3. Apply the template to specific dashboards

### Themes

Superset supports system-level theme definitions with dark mode support. Themes can be configured by administrators and applied globally.

---

## 5. Common Tasks

### Connect a New Database

**Goal:** Add a PostgreSQL database as a data source.

**Steps:**
1. Navigate to **Settings > Database Connections > + Database**
2. Select "PostgreSQL" from the database type list
3. Enter connection details:
   ```text
   Host: db.example.com
   Port: 5432
   Database: analytics
   Username: readonly_user
   Password: ********
   ```
4. Click **Test Connection** to verify
5. Click **Connect**

**Verify:** The new database appears in the database list and in SQL Lab's database dropdown.

**If it fails:** Check that the database host is reachable from the Superset server and that the credentials are correct. Ensure the required Python driver (e.g., `psycopg2`) is installed.

### Create a Dataset from a SQL Query

**Goal:** Save a complex query as a reusable dataset for charts.

**Steps:**
1. Open **SQL Lab > SQL Editor**
2. Write and run your query
3. Click **Save > Save Dataset**
4. Enter a name and select the target schema
5. Click **Save**

**Verify:** The dataset appears under **Datasets** and is available when creating new charts.

### Build a Dashboard with Filters

**Goal:** Create an interactive dashboard with a date and category filter.

**Steps:**
1. Create 3-4 charts from the same dataset
2. Go to **Dashboards > + Dashboard**
3. Drag your charts onto the canvas
4. Click the filter icon to add a **Native Filter**
5. Add a "Time Range" filter targeting the date column
6. Add a "Value" filter targeting the category column
7. Map each filter to the relevant charts
8. Click **Save**

**Verify:** Changing filter values updates all mapped charts in real time.

### Export and Import Dashboards

**Goal:** Move dashboards between Superset instances.

**Export via CLI:**
```bash
superset export_dashboards -f dashboards_backup.zip
```

**Import via CLI:**
```bash
superset import_dashboards -p dashboards_backup.zip -u admin
```

**Export via API:**
```bash
curl -X GET "http://localhost:8088/api/v1/assets/export/" \
  -H "Authorization: Bearer $TOKEN" \
  -o assets.zip
```

**Import via API:**
```bash
curl -X POST "http://localhost:8088/api/v1/assets/import/" \
  -H "Authorization: Bearer $TOKEN" \
  -F "bundle=@assets.zip" \
  -F "passwords={}" \
  -F "ssh_tunnel_passwords={}"
```

> [!TIP]
> The import/export format is a ZIP file containing YAML definitions for databases, datasets, charts, dashboards, and saved queries. You can version-control these files for infrastructure-as-code workflows.

### Embed a Dashboard in an External Application

**Goal:** Display a Superset dashboard inside your web application.

**Steps:**
1. Configure an embedded dashboard via the API:
   ```bash
   curl -X POST "http://localhost:8088/api/v1/dashboard/<id>/embedded" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"allowed_domains": ["https://yourapp.com"]}'
   ```
2. Install the SDK in your frontend:
   ```bash
   npm install @superset-ui/embedded-sdk
   ```
3. Embed the dashboard:
   ```javascript
   import { embedDashboard } from '@superset-ui/embedded-sdk';

   embedDashboard({
     id: '<embedded-uuid>',
     supersetDomain: 'https://superset.example.com',
     mountPoint: document.getElementById('dashboard-container'),
     fetchGuestToken: () => fetchGuestTokenFromBackend(),
     dashboardUiConfig: {
       hideTitle: true,
       hideChartControls: true,
       hideTab: false,
     },
   });
   ```
4. The SDK handles automatic guest token refresh before expiry

**Verify:** The dashboard renders inside your application with the specified UI configuration.

**Embedded dashboard query parameters:**

| Parameter | Description |
|---|---|
| `uiConfig` | Visual configuration (hideTitle, hideTab, hideChartControls) |
| `show_filters` | Show the filter panel |
| `expand_filters` | Auto-expand filters on load |
| `native_filters_key` | Apply saved filter configuration |
| `permalink_key` | Load a shared dashboard state |

### Schedule a Weekly Report

**Goal:** Send a PDF of a dashboard to the team every Monday morning.

**Steps:**
1. Go to **Settings > Alerts & Reports > + Report**
2. Set name: "Weekly Sales Report"
3. Select the target dashboard
4. Set schedule: `0 9 * * 1` (every Monday at 9:00 AM)
5. Select timezone
6. Add email recipients
7. Choose format: PDF
8. Activate the report

**Verify:** Check the report log after the next scheduled run to confirm delivery.

### Upload Data from a CSV File

**Goal:** Load a CSV file as a new dataset.

**Steps:**
1. Navigate to **Settings > Database Connections**
2. Select a database that allows file upload (`allow_file_upload: true`)
3. Click **Upload > CSV**
4. Select the file and configure column types
5. Choose the target table name and schema
6. Click **Upload**

**Verify:** The new table appears in the database and is queryable in SQL Lab.

> [!NOTE]
> Superset supports CSV, Excel (.xlsx), and Parquet file uploads through the `CSVReader`, `ExcelReader`, and `ColumnarReader` upload handlers.

### Set Up Row-Level Security

**Goal:** Restrict data access so each team sees only their own data.

**Steps:**
1. Go to **Settings > Row Level Security > + Rule**
2. Enter a name and description
3. Select the filter type
4. Choose the target tables
5. Assign roles (e.g., "Sales Team")
6. Define the SQL clause: `team_id = 'sales'`
7. Optionally set a group key for organization
8. Save the rule

**Verify:** Users with the "Sales Team" role only see rows where `team_id = 'sales'`.

### Use the Extensions CLI

**Goal:** Create a custom Superset extension.

```bash
pip install superset-extensions-cli
superset-extensions-cli init \
  --publisher my-org \
  --name dashboard-widgets \
  --display-name "Dashboard Widgets" \
  --version 0.1.0 \
  --license Apache-2.0 \
  --frontend \
  --backend
```

Build and bundle the extension:
```bash
superset-extensions-cli build
superset-extensions-cli bundle -o my-extension.zip
```

Validate the extension:
```bash
superset-extensions-cli validate
```

### Load Example Data

**Goal:** Populate Superset with example datasets and dashboards for exploration.

```bash
superset load_examples
```

| Flag | Description |
|---|---|
| `--load-test-data` / `-t` | Load additional test data |
| `--load-big-data` / `-b` | Load large-scale test data |
| `--only-metadata` / `-m` | Only load metadata, skip actual data |
| `--force` / `-f` | Force reload even if tables already exist |

### Test a Database Connection

**Goal:** Validate a database URI before adding it to Superset.

```bash
superset test_db "postgresql+psycopg2://user:pass@host:5432/db"
```

Pass additional connection arguments as JSON:
```bash
superset test_db "postgresql+psycopg2://user:pass@host:5432/db" \
  -c '{"connect_timeout": 10}'
```

### Use the MCP Service

**Goal:** Access Superset programmatically via the Model Context Protocol.

**Start the MCP server:**
```bash
superset mcp run --host 0.0.0.0 --port 5008
```

| Option | Default | Description |
|---|---|---|
| `--host` | `127.0.0.1` | Host to bind to |
| `--port` | `5008` | Port to bind to |
| `--debug` | off | Enable debug mode |

Environment variables:
- `FASTMCP_TRANSPORT` — transport mode: `stdio` (default) or `http`
- `FASTMCP_HOST` — host override (default: `127.0.0.1`)
- `FASTMCP_PORT` — port override (default: `5008`)

---

## 6. Troubleshooting

Use this diagnostic flow to narrow down issues:

```text
Is Superset running?
+--> No --> Check container logs: docker compose logs superset
|           Check process: ps aux | grep superset
+--> Yes --> Can you reach the UI?
             +--> No --> Check port binding (8088)
             |           Check reverse proxy / firewall
             +--> Yes --> Is your issue with...
                          +--> A chart? --> Check dataset, query, viz type
                          +--> SQL Lab? --> Check database connection
                          +--> A dashboard? --> Check chart dependencies
                          +--> Reports? --> Check Celery worker + beat
                          +--> Performance? --> Check cache config + query complexity
```

### Error: `ERROR:superset:Refusing to start due to insecure SECRET_KEY`

**Cause:** Superset detected a default or missing secret key in a non-debug environment.

**Solution:**
```bash
export SUPERSET_SECRET_KEY=$(openssl rand -base64 42)
```

**Prevention:** Set `SUPERSET_SECRET_KEY` in your `.env` or Kubernetes Secret before first startup.

### Error: Chart displays "No data" when data exists

**Cause:** Time range filter excludes all rows, or the metric/dimension configuration is incorrect.

**Solution:**
1. Verify the time range includes dates present in the dataset
2. Check that the metric column contains non-null values
3. Preview data in SQL Lab with the same filters

**Prevention:** Use "No filter" time range during initial chart development.

### Error: `celery.exceptions.NotRegistered`

**Cause:** The Celery worker cannot find the task module.

**Solution:**
1. Ensure the worker starts with `--app=superset.tasks.celery_app:app`
2. Verify `superset.tasks` is importable from the worker's Python environment

**Prevention:** Use the Docker Compose setup, which configures workers correctly.

### Error: SQL Lab query runs indefinitely

**Cause:** The query is too complex or the database is under heavy load.

**Solution:**
1. Cancel the query from SQL Lab
2. Add `LIMIT` to reduce result set size
3. Check database-side query timeout settings

**Prevention:** Use query cost estimation before running expensive queries. Configure `SQLLAB_TIMEOUT` in `superset_config.py`.

### Error: `OSError: [Errno 99] Cannot assign requested address`

**Cause:** The bind address is not available on the host.

**Solution:**
```bash
superset run --host 0.0.0.0 -p 8088
```

**Prevention:** Use `0.0.0.0` instead of `127.0.0.1` when running inside Docker.

### Error: Dashboard filters do not affect certain charts

**Cause:** The filter is not mapped to those charts, or the charts use different datasets.

**Solution:**
1. Edit the native filter and verify the "Scoping" tab includes the affected charts
2. Ensure charts share the same dataset or have compatible column names

**Prevention:** Map filters explicitly to all target charts when creating them.

### Error: `ReportScheduleNotFoundError` when running reports

**Cause:** The report schedule was deleted or the ID is invalid.

**Solution:**
1. Verify the report exists in **Settings > Alerts & Reports**
2. Re-create the schedule if it was deleted

**Prevention:** Do not delete reports that are referenced by external integrations.

### Error: `TimeoutError` during CSV upload

**Cause:** The file is too large for the default upload timeout.

**Solution:**
1. Increase upload-related timeout settings in configuration
2. Use SQL Lab to `COPY` data directly into the database for very large files

**Prevention:** For files larger than 100 MB, use direct database import tools instead of the UI uploader.

### Error: Embedded dashboard shows blank iframe

**Cause:** The embedding domain is not in the `allowed_domains` list, or the guest token is expired.

**Solution:**
1. Verify `allowed_domains` includes your application's origin
2. Check that the `fetchGuestToken` function returns a valid, non-expired token

**Prevention:** Implement automatic token refresh using the SDK's built-in refresh mechanism.

### Error: `Leftover Debug Statement Polluting Console in ZoomConfigControl` (#39622)

**Cause:** A debug `console.log` statement was left in the ZoomConfigControl component.

**Solution:** This is a known issue (community issue #39622). It does not affect functionality — only console output.

**Prevention:** This will be fixed in a future release.

### Error: `QueryClauseValidationException`

**Cause:** A SQL clause (WHERE, HAVING) contains disallowed syntax.

**Solution:**
1. Review the query clause for syntax errors
2. Remove any statements not allowed by the SQL validator (e.g., sub-selects in WHERE if restricted)

**Prevention:** Use the SQL Lab query preview to validate clauses before using them in chart configurations.

### Error: `SupersetGenericDBErrorException` when connecting to a database

**Cause:** The SQLAlchemy URI is malformed or the database is unreachable.

**Solution:**
1. Use `superset test_db <uri>` to validate the connection
2. Verify network connectivity to the database host
3. Check that the correct driver package is installed

**Prevention:** Always test connections before saving database configurations.

### Error: OAuth2 authentication fails for database connections

**Cause:** OAuth2 configuration is incomplete or tokens are expired.

**Solution:**
1. Verify the OAuth2 configuration for the database connection
2. Check token expiry and refresh token availability
3. Re-authenticate through the database connection's OAuth2 flow

**Prevention:** Monitor token expiry and configure automatic refresh where supported.

> [!CAUTION]
> When troubleshooting database connections, never share SQLAlchemy URIs in plain text — they contain credentials. Use `superset re_encrypt_secrets` if you suspect key exposure.

---

## 7. FAQ

**Q: What databases does Superset support?**

Superset supports any database with a SQLAlchemy-compatible driver. This includes PostgreSQL, MySQL, SQLite, BigQuery, Snowflake, Trino, Presto, ClickHouse, DuckDB, Apache Druid, Apache Hive, Databricks, Microsoft SQL Server, Oracle, Redshift, and 60+ others. The `superset/db_engine_specs/` directory contains 73 engine specification modules. Each database engine may require its own Python driver package.

**Q: Can I use Superset without Docker?**

Yes. Install via pip (`pip install apache-superset`) and run directly with Python. You will need to set up PostgreSQL and Redis separately for production use.

**Q: How do I reset the admin password?**

Use the Flask-AppBuilder CLI:
```bash
superset fab reset-password --username admin --password new_password
```

**Q: Can I create charts without writing SQL?**

Yes. Superset's Explore view provides a no-code chart builder. Select a dataset, choose metrics and dimensions using drag-and-drop controls, and the query is generated automatically.

**Q: How do I add a custom visualization plugin?**

Use the Yeoman generator to scaffold a new plugin:
```bash
npm install -g yo @superset-ui/generator-superset
mkdir superset-plugin-chart-custom
cd superset-plugin-chart-custom
yo @superset-ui/superset
```
Build the plugin and register it in `MainPreset.js`. Alternatively, use the newer `superset-extensions-cli init` command to scaffold an extension with both frontend and backend components.

**Q: What is the difference between a dataset and a database?**

A **database** is a connection to an external data source (PostgreSQL, MySQL, etc.). A **dataset** is a specific table, view, or saved query within a database that Superset uses as the basis for charts.

**Q: How do I enable dark mode?**

Superset supports theme configuration including dark mode. Configure themes through the admin settings. The embedded SDK also supports `themeMode` options: `"default"`, `"dark"`, or `"system"`.

**Q: Can I version-control my dashboards?**

Yes. Use `superset export_dashboards` to export dashboards as ZIP files containing YAML definitions. These can be committed to Git and imported into other instances with `superset import_dashboards`.

**Q: How do I upgrade Superset?**

1. Back up your metadata database
2. Update the Superset package: `pip install --upgrade apache-superset`
3. Run database migrations: `superset db upgrade`
4. Re-initialize: `superset init`
5. Restart the application

For Docker deployments, update the image tag and restart containers.

**Q: What is the `superset init` command?**

`superset init` creates default roles and permissions. Run it after installation and after database migrations to ensure all security metadata is current.

**Q: How do I connect to a database that requires SSH tunneling?**

Superset supports SSH tunnel configuration when adding database connections. Provide the SSH host, port, username, and private key in the database connection form or via the import API's `ssh_tunnel_passwords` and `ssh_tunnel_private_keys` parameters.

**Q: Can I use template variables in SQL queries?**

Yes. SQL Lab supports Jinja templating. Use `{{ var }}` syntax to reference template variables. Built-in variables include `{{ from_dttm }}`, `{{ to_dttm }}`, and `{{ row_limit }}`.

**Q: How do I re-encrypt secrets after changing the SECRET_KEY?**

Use the CLI command:
```bash
superset re_encrypt_secrets --previous_secret_key "old_key_here"
```

This re-encrypts all stored database passwords and other encrypted fields with the new key.

**Q: What ports does Superset use?**

| Service | Default Port |
|---|---|
| Web application | 8088 |
| MCP service | 5008 |
| Redis | 6379 |
| PostgreSQL | 5432 |
| WebSocket service | Configured per deployment |
| Webpack dev server | `WEBPACK_DEVSERVER_PORT` env var |

**Q: Can multiple users edit a dashboard simultaneously?**

Dashboard editing is not collaborative in real time. Only one user should edit a dashboard at a time to avoid overwriting changes. The WebSocket service provides real-time event streaming for dashboard viewing, not editing.

**Q: How do I migrate legacy chart types to ECharts?**

Use the visualization migration CLI:
```bash
superset migrate_viz upgrade --viz_type <type>
```

To migrate specific charts by ID:
```bash
superset migrate_viz upgrade --viz_type <type> --id 42 --id 43
```

To revert a migration:
```bash
superset migrate_viz downgrade --viz_type <type>
```

**Q: How do I factory-reset a Superset instance?**

```bash
superset factory_reset --username admin --silent
```

Optionally exclude specific users or roles:
```bash
superset factory_reset --username admin --exclude-users "service_account" --exclude-roles "Custom_Role"
```

> [!CAUTION]
> `factory_reset` is destructive and irreversible. It removes all dashboards, charts, datasets, and associated data. Back up your metadata database before running this command.

**Q: How do I sync tags across objects?**

Use the CLI command:
```bash
superset sync_tags
```

This synchronizes tag associations across all tagged objects in the metadata database.

**Q: What is the Superset Meta Database?**

When `ENABLE_SUPERSET_META_DB` feature flag is enabled, Superset registers itself as a data source via Shillelagh and the `superset://` SQLAlchemy dialect. This allows querying Superset's own metadata as if it were an external database.

---

_Generated May 2026 from apache/superset at 970b5bc. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._