reflex-dev/reflex · error · ConfigError

TOML support is not available. Please use Python 3.11 or lat

Error message

TOML support is not available. Please use Python 3.11 or later.

What it means

ConfigError raised when the stdlib tomllib module cannot be imported while parsing a TOML config. tomllib only exists on Python 3.11+, so this fires on older interpreters.

Source

Thrown at packages/reflex-hosting-cli/src/reflex_cli/core/config.py:255

        Args:
            pyproject_path: The path to the TOML file. Defaults to "pyproject.toml" in the current directory.
            env: The environment to load the config for.

        Returns:
            Config: A Config instance with the values from the TOML file.

        Raises:
            ConfigError: If the TOML file is not found.

        """
        if not pyproject_path.exists():
            raise ConfigError(f"Config file not found at {pyproject_path}.")

        try:
            import tomllib
        except ImportError as e:
            raise ConfigError(
                "TOML support is not available. Please use Python 3.11 or later."
            ) from e

        with pyproject_path.open("rb") as file:
            pyproject_data = tomllib.load(file)
            if not isinstance(pyproject_data, dict):
                raise ConfigError(
                    f"Invalid TOML file format at {pyproject_path}. Expected a dictionary."
                )
            tools = pyproject_data.get("tool", {})
            if not isinstance(tools, dict):
                raise ConfigError(
                    f"Invalid TOML file format at {pyproject_path}. Expected 'tool' to be a dictionary."
                )
            if "reflex-cloud" not in tools:
                raise ConfigError(
                    f"Invalid TOML file format at {pyproject_path}. Expected 'tool.reflex-cloud' to be present."
                )

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Upgrade to Python 3.11 or later and recreate your virtualenv
Or point the CLI at a YAML config (rxconfig.yaml with PyYAML installed) to avoid tomllib entirely

Example fix

# before: python3.10 -m reflex_cli ...

# after
python3.12 -m reflex_cli ...  # tomllib available

Defensive patterns

Strategy: validation

Validate before calling

import sys
if sys.version_info < (3, 11):
    raise RuntimeError("reflex-hosting-cli TOML config requires Python 3.11+")
config = CloudConfig.from_toml(p)

Try / catch

try:
    config = CloudConfig.from_toml(p)
except ConfigError as e:
    if "Python 3.11" in str(e):
        config = CloudConfig.from_yaml(yaml_path)  # requires pyyaml
    else:
        raise

Prevention

Pin Python >= 3.11 in your project (.python-version, CI image, Dockerfile)
Prefer YAML config when you must support older Pythons

When it happens

Trigger: Calling CloudConfig.from_toml on Python < 3.11, where `import tomllib` raises ImportError.

Common situations: Running the hosting CLI with an older system Python (3.9/3.10); a venv created from an outdated interpreter; CI images pinned to old Python versions.

Related errors

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/dfa85a054708ff62. Report an issue: GitHub.