tirth8205/code-review-graph · error · RuntimeError

TOML parsing requires the 'tomli' package on Python < 3.11.

Error message

TOML parsing requires the 'tomli' package on Python < 3.11. Install it with:  pip install tomli

What it means

load_config() parses TOML config files using tomllib (stdlib, Python 3.11+). On older Pythons it falls back to the optional tomli package; if tomli is not installed, tomllib is None and the function raises RuntimeError telling you to install tomli. Every daemon code path that reads config (startup, status, add/remove repo, config reload) goes through this function.

Source

Thrown at code_review_graph/daemon.py:161

# ---------------------------------------------------------------------------
# Loading
# ---------------------------------------------------------------------------


def load_config(path: Path | None = None) -> DaemonConfig:
    """Load daemon configuration from a TOML file.

    Args:
        path: Explicit config path.  Falls back to :func:`default_config_path`.

    Returns:
        A fully-validated :class:`DaemonConfig`.

    Raises:
        RuntimeError: If ``tomllib`` / ``tomli`` is unavailable on Python < 3.11.
    """
    if tomllib is None:
        raise RuntimeError(
            "TOML parsing requires the 'tomli' package on Python < 3.11. "
            "Install it with:  pip install tomli"
        )

    config_path = path or default_config_path()

    if not config_path.exists():
        logger.info("Config file not found at %s — using defaults", config_path)
        return DaemonConfig()

    with open(config_path, "rb") as fh:
        raw: dict[str, Any] = tomllib.load(fh)

    # -- [daemon] section ---------------------------------------------------
    daemon_section: dict[str, Any] = raw.get("daemon", {})
    session_name: str = daemon_section.get("session_name", "crg-watch")
    log_dir = Path(daemon_section.get("log_dir", str(DaemonConfig().log_dir)))
    poll_interval: int = int(daemon_section.get("poll_interval", 2))

View on GitHub (pinned to b58668751a)

Solutions

  1. pip install tomli (or add it to requirements for Python < 3.11: 'tomli; python_version < "3.11"')
  2. Upgrade the runtime to Python 3.11+ where tomllib is built in
  3. Verify with `python -c "import tomli"` that the active venv actually has it

Example fix

# before
RuntimeError: TOML parsing requires the 'tomli' package on Python < 3.11.

# after
$ pip install 'tomli; python_version < "3.11"'
$ code-review-graph daemon start
Defensive patterns

Strategy: validation

Validate before calling

import sys
if sys.version_info < (3, 11):
    try:
        import tomli  # noqa: F401
    except ImportError:
        raise SystemExit("Install tomli: pip install tomli")

from code_review_graph.daemon import load_config
cfg = load_config()

Type guard

def tomllib_available() -> bool:
    import sys
    if sys.version_info >= (3, 11):
        return True
    try:
        import tomli  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    cfg = load_config(path)
except RuntimeError as e:
    if 'tomli' in str(e):
        subprocess.run([sys.executable, '-m', 'pip', 'install', 'tomli'], check=True)
        cfg = load_config(path)
    else:
        raise

Prevention

When it happens

Trigger: Running the daemon (start/status/add/remove) on Python < 3.11 in an environment where the tomli package is not installed — e.g. it is missing from package extras or was pruned from a venv.

Common situations: Deploying to older Linux distros or CI images with Python 3.9/3.10, minimal containers, or installing the package from source without its optional dependencies.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of tirth8205/code-review-graph@b58668751a (2026-08-28). Data as JSON: /api/errors/a85a77a2186f9339. Report an issue: GitHub.