{"record":{"id":"d8a08e443a8816d8","repo":"bmad-code-org/BMAD-METHOD","slug":"error-python-3-11-is-required-stdlib-tomllib","errorCode":null,"errorMessage":"error: Python 3.11+ is required (stdlib `tomllib` not found).","messagePattern":"error: Python 3\\.11\\+ is required \\(stdlib `tomllib` not found\\)\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"critical","filePath":"src/scripts/resolve_config.py","lineNumber":21,"sourceCode":"# requires-python = \">=3.11\"\n# ///\n\"\"\"Resolve BMad's four central TOML layers to JSON.\"\"\"\n\nimport argparse\nimport json\nimport sys\nfrom pathlib import Path\n\n# Installed scripts are consumer files, not a location for interpreter caches.\nsys.dont_write_bytecode = True\n\ntry:\n    from config_utils import ConfigError, load_central_config\nexcept ModuleNotFoundError as error:\n    if error.name != \"tomllib\":\n        raise\n    sys.stderr.write(\"error: Python 3.11+ is required (stdlib `tomllib` not found).\\n\")\n    raise SystemExit(3) from None\n\n\n_MISSING = object()\n\n\ndef extract_key(data, dotted_key: str):\n    current = data\n    for part in dotted_key.split(\".\"):\n        if isinstance(current, dict) and part in current:\n            current = current[part]\n        else:\n            return _MISSING\n    return current\n\n\ndef main() -> int:\n    parser = argparse.ArgumentParser(\n        description=\"Resolve BMad central config using four-layer TOML merge.\"","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/bmad-code-org/BMAD-METHOD/blob/b70486b9bdcb0a404d329e2a763b57964e7f1360/src/scripts/resolve_config.py#L3-L39","documentation":"This is a runtime interpreter-version guard, not a logic error. The script imports `load_central_config` from the local `config_utils` module, which itself does `import tomllib` (config_utils.py:5). `tomllib` is a standard-library module that ships only with Python 3.11 and newer. When run on Python < 3.11, that import raises `ModuleNotFoundError(name='tomllib')`; the wrapper narrows on `error.name == 'tomllib'`, prints a one-line actionable message, and terminates the process via `SystemExit(3)`. It exists because the repository declares no `pyproject.toml` / `requires-python` / `.python-version`, so this import-time check is the only thing keeping the tool from failing later with a confusing traceback.","triggerScenarios":"Invoking `resolve_config.py` (directly or through a wrapper) with an interpreter whose `sys.version_info < (3, 11)`. Concretely: `python3.10 src/scripts/resolve_config.py`, or any `#!/usr/bin/env python3` shebang that resolves to a 3.10-or-older `python3` on PATH; running the project's tests with the wrong interpreter; a venv created from a pre-3.11 base interpreter; or a CI image pinned to an older Python. The error fires before any config file is read, so missing or malformed `*.toml` is NOT a cause.","commonSituations":"1) System `python3` on older LTS distros (e.g. Ubuntu 20.04 ships 3.8, Debian 11 ships 3.9) resolving the shebang. 2) A virtualenv built from a pre-3.11 base interpreter while the developer assumes `python3` means 'latest'. 3) pyenv / asdf / mise shims pointing at an older Python. 4) CI matrix accidentally including 3.9/3.10, or a Docker base image like `python:3.10-slim`. 5) A toolchain manager (conda, uv, poetry) that created the env with an older default. 6) An alias `alias python=python3.10` lingering in the shell.","solutions":["Run the script with Python 3.11+: `python3.11 src/scripts/resolve_config.py` (or `python3.12`). Verify with `python3 --version` first.","Recreate the virtualenv on a 3.11+ base: `python3.12 -m venv .venv && source .venv/bin/activate`, then re-run.","Pin the project to a 3.11+ interpreter in your version manager: `pyenv local 3.12` / `mise use python@3.12` / `asdf local python 3.12.x`.","If the interpreter is fixed at < 3.11 and cannot be upgraded, install the `tomli` backport and add a shim: `pip install tomli` plus `if sys.version_info < (3,11): import tomli as tomllib` in config_utils.py (only if the project owner accepts backport support — this is a code change, not a config fix).","On CI, bump the Python setup step: `actions/setup-python@v5` with `python-version: '3.11'` or newer, or update the Docker base image to `python:3.11-slim`+."],"exampleFix":"# before — shebang floats to whatever 'python3' resolves to\n#!/usr/bin/env python3\n\n# after — pin to a 3.11+ interpreter explicitly\n#!/usr/bin/env python3.12\n\n# or, in CI (.github/workflows/*.yml)\n# before\n- uses: actions/setup-python@v5\n  with:\n    python-version: '3.10'\n# after\n- uses: actions/setup-python@v5\n  with:\n    python-version: '3.12'","handlingStrategy":"validation","validationCode":"import sys\n\nMIN_PY = (3, 11)\n\nif sys.version_info < MIN_PY:\n    sys.exit(\n        f\"error: Python {MIN_PY[0]}.{MIN_PY[1]}+ is required \"\n        f\"(running {sys.version_info.major}.{sys.version_info.minor}).\"\n    )\n\n# Safe to invoke resolve_config / config_utils here — tomllib is guaranteed present.\nimport subprocess, sys\nsubprocess.run([sys.executable, \"src/scripts/resolve_config.py\"], check=True)","typeGuard":null,"tryCatchPattern":"# The guard raises SystemExit(3) at import time, so catch it only at a\n# process/subprocess boundary — never around the import itself, which would\n# mask a genuinely broken environment.\nimport subprocess, sys\n\nproc = subprocess.run(\n    [sys.executable, \"src/scripts/resolve_config.py\"],\n    capture_output=True, text=True,\n)\nif proc.returncode == 3 and \"tomllib\" in proc.stderr:\n    raise RuntimeError(\n        \"resolve_config needs Python 3.11+; current interpreter is \"\n        f\"{sys.version.split()[0]}.\"\n    )\nraise SystemExit(proc.returncode)","preventionTips":["Pin the project interpreter explicitly: add a `.python-version` (pyenv/asdf/mise) or `requires-python = '>=3.11'` in a `pyproject.toml` so the failure surfaces at install time, not at first run.","In wrappers and CI, call the script via the venv's absolute interpreter (`$VIRTUAL_ENV/bin/python` or `python3.12`) rather than a bare `python3` that PATH can resolve differently across machines.","Add a one-line preflight check at the top of any orchestrator: `assert sys.version_info >= (3, 11), 'Python 3.11+ required (tomllib).'`.","Lock CI to a 3.11+ matrix and fail fast on older versions; do not let a 3.10 cell pass and accumulate broken artifacts.","Document the minimum interpreter in the README next to the install command so users create the venv with the right base."],"tags":["python","python-version","tomllib","dependency","startup","interpreter"],"backgroundTag":null,"analyzedSha":"b70486b9bdcb0a404d329e2a763b57964e7f1360","analyzedAt":"2026-08-13T01:21:12.247Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}