// troubleshooting guide · apache superset

Superset Refusing to Start Due to Insecure SECRET_KEY

Status
Workaround available
platforms:
Self-hosted, Docker, Kubernetes
updated:
November 16, 2026
reports:
4
Method
how we research
Share

RUNBOOK · apache-superset/insecure-secret-key4 FIXES

// quick answer

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.

Most likely fix: Generate and set a strong key

How to fix it

// try these in order, the most common fix is first

  1. FIX 1Generate and set a strong key

    1. 01Run openssl rand -base64 42
    2. 02Add SECRET_KEY = '<value>' to superset_config.py, or export SUPERSET_SECRET_KEY=<value>
    3. 03Restart Superset
    Did this fix it?
  2. FIX 2Override the Docker default

    1. 01Set SUPERSET_SECRET_KEY in docker/.env-local or your compose environment
    2. 02Recreate the containers with docker compose up -d --force-recreate
    Did this fix it?
  3. FIX 3Rotate the key without losing connections

    1. 01Set PREVIOUS_SECRET_KEY to the old key and SECRET_KEY to the new one
    2. 02Run superset re_encrypt_secrets
    3. 03Remove PREVIOUS_SECRET_KEY afterwards
    Did this fix it?
  4. FIX 4Confirm the config is loaded

    1. 01Check SUPERSET_CONFIG_PATH points to your superset_config.py
    2. 02Run the CLI with the same environment as the web service
    Did this fix it?

SANDBOX · apache-superset RUNS IN YOUR BROWSER

Try it: browse a sample shop and watch visitors, funnels and live data arrive

A hands-on Apache Superset-style sandbox, including the spots where users get stuck. See where problems like this one start. 1-2 minutes, nothing is saved.

Symptoms

The web server or 'superset db upgrade' exits with 'Refusing to start due to insecure SECRET_KEY'.

Why it happens

  • C-01SECRET_KEY still the shipped default
  • C-02Docker Compose using the bundled TEST_NON_DEV_SECRET
  • C-03superset_config.py not loaded (SUPERSET_CONFIG_PATH not set)

// this guide also covers

  • refusing to start due to insecure secret_key
  • superset secret key error
  • superset SUPERSET_SECRET_KEY
  • superset won't start

Still not working?

If Apache Superset keeps failing, you're not alone. See every Apache Superset problem users report or the alternatives people switch to.

Done fighting Apache Superset? Our small team builds your own Apache Superset alternative, or any software you need: web, mobile, games, desktop. Price agreed together.

Talk to us

Watch Apache Superset Get an email when its price changes, it has an outage, or we publish a new fix. No spam.

Fixed it? Share this guide

Other Apache Superset errors

All 14 Apache Superset errors and fixes →