Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Apache Superset in Docker refuses to start because of the default SECRET_KEY

ErrorSuperset requires a user-specified SECRET_KEY to start up

Short answer

Superset requires a SECRET_KEY you set yourself and refuses to start without one. Generate a key with openssl rand -base64 42, put it in superset_config.py or in SUPERSET_SECRET_KEY, and make sure the container really loads that file. If you change the key on an existing install, rotate it, do not just replace it.

  • Applies to Apache Superset 4.x/5.x, Docker Engine 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the container log. The first lines after start show whether it stopped over the key.

    docker logs --tail 50 superset_app
  2. 2Match what you see, then jump to its fix

    1. 1The container exits at start and no SECRET_KEY is set in the config or environmentNo SECRET_KEY was set at allFix
    2. 2The key is in superset_config.py on the host, yet the container still complainsThe config file exists but Superset never loads itFix
    3. 3It starts, but saved database passwords or sessions break after you swapped the keyThe key was changed on an install that already holds encrypted dataFix

What does the error look like?

  • Superset requires a user-specified SECRET_KEY to start up
  • You MUST set this for production environments or the server will refuse to start

Cause 1 of 3

No SECRET_KEY was set at all

1Check

The docs say Superset requires a user-specified SECRET_KEY and the server refuses to start without one for production. Look for the setting in your config file and the container environment.

docker exec superset_app env | grep -i SECRET
docker exec superset_app sh -c 'grep -n SECRET_KEY "$SUPERSET_CONFIG_PATH"'

2Fix

Generate a strong key and set it. Keep it out of version control.

openssl rand -base64 42

# superset_config.py
import os
SECRET_KEY = os.environ.get("SUPERSET_SECRET_KEY")

# then start the container with
#   -e SUPERSET_SECRET_KEY=<the generated value>

3Verify

Restart the container and read the log; it reaches the web server start.

docker restart superset_app
docker logs --tail 20 superset_app

Confirmed by superset.apache.org

Did this fix it?

Cause 2 of 3

The config file exists but Superset never loads it

1Check

Superset reads the file only if it is on the PYTHONPATH or if SUPERSET_CONFIG_PATH holds its full path. A file that is not mounted into the container, or mounted at another path, is never read.

docker exec superset_app sh -c 'echo $SUPERSET_CONFIG_PATH; ls -l "$SUPERSET_CONFIG_PATH"'

2Fix

Mount the file into the container and point SUPERSET_CONFIG_PATH at its full path.

docker run -d --name superset_app -p 8088:8088 \
  -v $(pwd)/superset_config.py:/app/superset_config.py \
  -e SUPERSET_CONFIG_PATH=/app/superset_config.py \
  -e SUPERSET_SECRET_KEY=<the generated value> \
  apache/superset:<tag>

3Verify

The file is visible at the path from inside the container, and the log no longer stops on the key.

docker exec superset_app ls -l /app/superset_config.py
docker logs --tail 20 superset_app

Confirmed by superset.apache.org

Did this fix it?

Cause 3 of 3

The key was changed on an install that already holds encrypted data

1Check

Superset encrypts stored secrets with the key. Replacing it without telling Superset about the old one leaves existing secrets unreadable. The docs describe a rotation with PREVIOUS_SECRET_KEY.

docker exec superset_app superset shell

2Fix

Put the old key in PREVIOUS_SECRET_KEY next to the new SECRET_KEY, save the config and run the re-encrypt command. Rotation also logs every user out, so plan it.

# superset_config.py
SECRET_KEY = "<new key>"
PREVIOUS_SECRET_KEY = "<old key>"

docker exec superset_app superset re-encrypt-secrets

3Verify

Open a saved database connection in the UI and test it.

docker logs --tail 20 superset_app

Confirmed by superset.apache.org

Did this fix it?

How do I stop it coming back?

  • Give every Superset instance its own key; never reuse one across development, staging and production.
  • Keep the key in an environment variable or a secrets manager, not in the repository.
  • Write the old key down before any rotation.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.