pallets/flask · error · RuntimeError

The environment variable {variable_name!r} is not set and as

Error message

The environment variable {variable_name!r} is not set and as such configuration could not be loaded. Set this variable and make it point to a configuration file

What it means

`Config.from_envvar(variable_name)` is a shortcut for `from_pyfile(os.environ[variable_name])` (src/flask/config.py:102-124). If the named environment variable is unset or empty and `silent=False` (the default), Flask raises this RuntimeError instead of proceeding without configuration. It exists so deployments fail loudly when the pointer to the config file is missing, rather than running with defaults.

Source

Thrown at src/flask/config.py:118

        self.root_path = root_path

    def from_envvar(self, variable_name: str, silent: bool = False) -> bool:
        """Loads a configuration from an environment variable pointing to
        a configuration file.  This is basically just a shortcut with nicer
        error messages for this line of code::

            app.config.from_pyfile(os.environ['YOURAPPLICATION_SETTINGS'])

        :param variable_name: name of the environment variable
        :param silent: set to ``True`` if you want silent failure for missing
                       files.
        :return: ``True`` if the file was loaded successfully.
        """
        rv = os.environ.get(variable_name)
        if not rv:
            if silent:
                return False
            raise RuntimeError(
                f"The environment variable {variable_name!r} is not set"
                " and as such configuration could not be loaded. Set"
                " this variable and make it point to a configuration"
                " file"
            )
        return self.from_pyfile(rv, silent=silent)

    def from_prefixed_env(
        self, prefix: str = "FLASK", *, loads: t.Callable[[str], t.Any] = json.loads
    ) -> bool:
        """Load any environment variables that start with ``FLASK_``,
        dropping the prefix from the env key for the config key. Values
        are passed through a loading function to attempt to convert them
        to more specific types than strings.

        Keys are loaded in :func:`sorted` order.

        The default loading function attempts to parse values as any

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

1. Export the variable pointing at your config file before starting the app: `export YOURAPP_SETTINGS=/etc/yourapp/settings.cfg`.
2. Verify the name matches exactly (env var names are case-sensitive) and that it is set in the actual runtime environment (Dockerfile `ENV`, compose `environment:`, systemd `Environment=`), not just your shell.
3. If the config file is optional, call `app.config.from_envvar('YOURAPP_SETTINGS', silent=True)` and handle the False return.
4. Consider `app.config.from_prefixed_env()` if you want config values directly from FLASK_* env vars instead of a pointer file.

Example fix

# before (shell)
python run.py  # YOURAPP_SETTINGS never set -> RuntimeError

# after (shell)
export YOURAPP_SETTINGS=/etc/yourapp/production.cfg
python run.py

# or in code, if optional:
app.config.from_envvar('YOURAPP_SETTINGS', silent=True)

import os

CONFIG_VAR = "MYAPP_SETTINGS"
if not os.environ.get(CONFIG_VAR):
    raise SystemExit(f"{CONFIG_VAR} is not set; export it to point at your config file")
app.config.from_envvar(CONFIG_VAR)

import os

def config_envvar_ready(name: str) -> bool:
    path = os.environ.get(name)
    return bool(path) and os.path.isfile(path)

try:
    app.config.from_envvar("MYAPP_SETTINGS")
except RuntimeError as exc:
    raise SystemExit(f"Configuration error: {exc}") from exc

When it happens

Trigger: Calling `app.config.from_envvar('YOURAPP_SETTINGS')` when that env var is not exported in the process environment, or is set to an empty string. A set-but-wrong path instead produces a file-not-found error from `from_pyfile`, not this one.

Common situations: Env var exported in an interactive shell but not in the service's environment (systemd, Docker, cron, supervisord); var set without `export` so child processes don't inherit it; typo or case mismatch in the variable name; WSGI servers (uWSGI/gunicorn under systemd) started with a scrubbed environment; CI runs missing the secret/vars block.

Related errors

• The session is unavailable because no secret key was set. S
• If an instance path is provided it must be absolute. A relat
• Working outside of application context. Attempted to use fu
• Working outside of request context. Attempted to use functi
• 'after_this_request' can only be used when a request context

AI-assisted analysis of pallets/flask@6a2f545bfd (2026-07-31). Data as JSON: /data/errors/7536e665f3a028b9.json. Report an issue: GitHub ↗.