mlflow/mlflow · critical · MlflowException

A static secret key needs to be set for CSRF protection. Ple

Error message

A static secret key needs to be set for CSRF protection. Please set the `MLFLOW_FLASK_SERVER_SECRET_KEY` environment variable before starting the server. For example:

export MLFLOW_FLASK_SERVER_SECRET_KEY='my-secret-key'

If you are using multiple servers, please ensure this key is consistent between them, in order to prevent validation issues.

What it means

MLflow's Flask auth server requires a static secret key for session signing, message flashing, and CSRF protection. The key is read from the `MLFLOW_FLASK_SERVER_SECRET_KEY` environment variable; if unset, server startup raises this error because CSRF tokens would not validate consistently across workers with an ephemeral key.

Source

Thrown at mlflow/server/auth/__init__.py:5865

    Args:
        app: The Flask app to enable authentication and authorization for.

    Returns:
        The app with authentication and authorization enabled.
    """
    global _auth_initialized

    _logger.warning(
        "This feature is still experimental and may change in a future release without warning"
    )

    # a secret key is required for flashing, and also for
    # CSRF protection. it's important that this is a static key,
    # otherwise CSRF validation won't work across workers.
    secret_key = MLFLOW_FLASK_SERVER_SECRET_KEY.get()
    if not secret_key:
        raise MlflowException(
            "A static secret key needs to be set for CSRF protection. Please set the "
            "`MLFLOW_FLASK_SERVER_SECRET_KEY` environment variable before starting the "
            "server. For example:\n\n"
            "export MLFLOW_FLASK_SERVER_SECRET_KEY='my-secret-key'\n\n"
            "If you are using multiple servers, please ensure this key is consistent between "
            "them, in order to prevent validation issues."
        )
    app.secret_key = secret_key

    # we only need to protect the CREATE_USER_UI route, since that's
    # the only browser-accessible route. the rest are client / REST
    # APIs that do not have access to the CSRF token for validation
    app.config["WTF_CSRF_CHECK_DEFAULT"] = False
    csrf = CSRFProtect()
    csrf.init_app(app)

    store.init_db(
        auth_config.database_uri,

View on GitHub (pinned to 6a27f2decc)

Solutions

Set the environment variable before starting: `export MLFLOW_FLASK_SERVER_SECRET_KEY='my-secret-key'`.
Add the variable to your Dockerfile/compose/systemd unit so it reaches the server process.
Use the same static key across all servers/workers to avoid CSRF validation mismatches.

Example fix

// before
mlflow server --app-name basic-auth
// after
export MLFLOW_FLASK_SERVER_SECRET_KEY='my-secret-key'
mlflow server --app-name basic-auth

Defensive patterns

Strategy: validation

Validate before calling

import os, sys
if not os.environ.get("MLFLOW_FLASK_SERVER_SECRET_KEY"):
    sys.exit("MLFLOW_FLASK_SERVER_SECRET_KEY must be set before starting the auth server")

Prevention

Export the secret key in every environment that launches the server (Docker, systemd, k8s manifests)
Share one static key across all replicas/workers
Add a startup smoke test that fails fast when auth is enabled without the key

When it happens

Trigger: Starting the MLflow server with `--app-name basic-auth` (auth enabled) without the `MLFLOW_FLASK_SERVER_SECRET_KEY` environment variable set.

Common situations: First-time auth setup where the env var was not exported; running under systemd/Docker/Kubernetes where the env var was not propagated into the container; multiple workers started with a per-worker random key.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of mlflow/mlflow@6a27f2decc (2026-08-29). Data as JSON: /api/errors/32586e2f3056edea. Report an issue: GitHub.