Apache Superset in Docker refuses to start because of the default SECRET_KEY
Superset requires a user-specified SECRET_KEY to start upShort 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.
Fix it fast
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_app2Match what you see, then jump to its fix
- 1
The container exits at start and no SECRET_KEY is set in the config or environmentNo SECRET_KEY was set at allFix - 2
The key is in superset_config.py on the host, yet the container still complainsThe config file exists but Superset never loads itFix - 3
It starts, but saved database passwords or sessions break after you swapped the keyThe key was changed on an install that already holds encrypted dataFix
- 1
What does the error look like?
Superset requires a user-specified SECRET_KEY to start upYou 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_appConfirmed by superset.apache.org
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_appConfirmed by superset.apache.org
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 shell2Fix
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-secrets3Verify
Open a saved database connection in the UI and test it.
docker logs --tail 20 superset_appConfirmed by superset.apache.org
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
Servers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fix