reflex-dev/reflex · error · ConfigError

Invalid TOML file format at {pyproject_path}. Expected 'tool

Error message

Invalid TOML file format at {pyproject_path}. Expected 'tool' to be a dictionary.

What it means

ConfigError raised when the top-level `tool` key in pyproject.toml is not a table. The CLI reads settings from [tool.reflex-cloud], so `tool` must be a dict for the lookup to proceed.

Source

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

        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."
                )
            data = tools["reflex-cloud"]
            if env:
                data = data.get("env", {}).get(env, {})
            data = cls._filter_dict(data)
        return cls(_cloud_config_path=pyproject_path, **data)

    @classmethod
    def from_yaml_or_toml_or_default(cls) -> Config:
        """Creates a Config instance from either a YAML or TOML file, or returns a default instance.

        Returns:
            Config: A Config instance with values from the YAML or TOML file, or a default instance if neither file exists.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Replace the `tool = ...` assignment with proper TOML tables: [tool.reflex-cloud] and other [tool.x] sections
Run a TOML linter / `tomllib` parse check over pyproject.toml
Recreate the file from a known-good Reflex project template

Example fix

# before (pyproject.toml)
tool = ["reflex-cloud"]

# after
[tool.reflex-cloud]
teardown_on_delete = true

Defensive patterns

Strategy: validation

Validate before calling

import tomllib
parsed = tomllib.loads(Path("pyproject.toml").read_text())
if not isinstance(parsed.get("tool"), dict):
    raise ValueError("'tool' must be a TOML table, e.g. [tool.reflex-cloud]")

Type guard

def has_tool_table(parsed: dict) -> bool:
    return isinstance(parsed.get("tool"), dict)

Try / catch

try:
    config = CloudConfig.from_toml(p)
except ConfigError as e:
    if "'tool' to be a dictionary" in str(e):
        fix_tool_section(p)  # convert `tool = ...` to [tool.*] tables
    else:
        raise

Prevention

Never assign a scalar/array to the `tool` key; always use [tool.x] table syntax
Lint pyproject.toml after structural edits

When it happens

Trigger: CloudConfig.from_toml where pyproject.toml defines `tool` as a scalar or array, e.g. `tool = "x"` or `tool = ["a"]`.

Common situations: Hand-editing pyproject.toml and assigning a value to `tool` instead of a [tool.*] table; a broken merge or template producing invalid structure.

Related errors

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