pallets/flask · error · RuntimeError

The environment variable

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) reads os.environ.get(variable_name). If the value is missing or empty (falsy) and silent is False, it raises RuntimeError telling you the named environment variable is not set and must point to a config file. This is the explicit-failure path; silent=True would return False instead.

Solutions

  1. Set the environment variable to an absolute path of a Python config file: export APP_SETTINGS=/etc/myapp/prod.py.
  2. Pass silent=True and handle the False return value if the config file is optional.
  3. Load your .env file (e.g. via python-dotenv) before calling from_envvar.

Example fix

# before
app.config.from_envvar('APP_SETTINGS')   # raises if unset

# after
app.config.from_envvar('APP_SETTINGS', silent=True)  # returns False if unset
# or ensure it is set: export APP_SETTINGS=/etc/myapp/prod.py
Defensive patterns

Strategy: validation

Validate before calling

import os

def env_config_present(var: str) -> bool:
    val = os.environ.get(var)
    return bool(val) and os.path.isfile(val)

Type guard

null

Try / catch

try:
    app.config.from_envvar('APP_SETTINGS')
except RuntimeError:
    app.config.from_object('mypkg.default_settings')

Prevention

When it happens

Trigger: Calling app.config.from_envvar('APP_SETTINGS') when APP_SETTINGS is unset or empty in the environment and silent=False (the default). The variable must hold a filesystem path to a Python config file that from_pyfile will then load.

Common situations: Deploying without setting the settings env var; forgetting to export it in the shell or systemd unit; a .env file not loaded by python-dotenv before from_envvar runs; renaming the env var in code but not in deployment.

Related errors

AI-assisted analysis of pallets/flask@3596b1ab61 (2026-08-11). Data as JSON: /api/errors/7536e665f3a028b9. Report an issue: GitHub.

Appendix: 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 3596b1ab61)