{"record":{"id":"5e5dad3ad359fd01","repo":"bmad-code-org/BMAD-METHOD","slug":"required-toml-file-not-found-path","errorCode":null,"errorMessage":"required TOML file not found: {path}","messagePattern":"required TOML file not found: (.+?)","errorType":"exception","errorClass":"ConfigError","httpStatus":null,"severity":"error","filePath":"src/scripts/config_utils.py","lineNumber":21,"sourceCode":"from __future__ import annotations\n\nimport tomllib\nfrom pathlib import Path\nfrom typing import Any, Iterable\n\n\nclass ConfigError(ValueError):\n    \"\"\"Raised when a present configuration layer cannot be used safely.\"\"\"\n\n\n_KEYED_MERGE_FIELDS = (\"code\", \"id\")\n\n\ndef load_toml(path: Path, *, required: bool = False) -> dict[str, Any]:\n    \"\"\"Load a TOML table, allowing absence only for optional layers.\"\"\"\n    if not path.exists():\n        if required:\n            raise ConfigError(f\"required TOML file not found: {path}\")\n        return {}\n    if not path.is_file():\n        raise ConfigError(f\"TOML layer is not a file: {path}\")\n    try:\n        with path.open(\"rb\") as stream:\n            parsed = tomllib.load(stream)\n    except tomllib.TOMLDecodeError as error:\n        raise ConfigError(f\"failed to parse {path}: {error}\") from error\n    except OSError as error:\n        raise ConfigError(f\"failed to read {path}: {error}\") from error\n    if not isinstance(parsed, dict):\n        raise ConfigError(f\"TOML layer did not parse to a table: {path}\")\n    return parsed\n\n\ndef _detect_keyed_merge_field(items: list[Any]) -> str | None:\n    if not items or not all(isinstance(item, dict) for item in items):\n        return None","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/bmad-code-org/BMAD-METHOD/blob/b70486b9bdcb0a404d329e2a763b57964e7f1360/src/scripts/config_utils.py#L3-L39","documentation":"config_utils.py's `load_toml` is the shared loader for every TOML config layer. When called with `required=True` and the path does not exist, it raises `ConfigError`. Required layers in this codebase are `_bmad/config.toml` (central config) and a skill's `customize.toml`; optional layers like `config.user.toml` simply return `{}` when absent. The error means a mandatory configuration file the tool needs to operate is missing.","triggerScenarios":"Running `render_skill` (or any tool calling `load_central_config` / `load_customization`) in a project that has no `_bmad/config.toml`; invoking a skill outside its installed directory so `customize.toml` is not found; a path typo or a misconfigured project root.","commonSituations":"A fresh checkout that skipped the BMAD init step; running from the wrong working directory; a renamed or moved `_bmad` folder; CI running in a shallow clone that excluded the config tree.","solutions":["Confirm the file at the reported path actually exists: `ls -la <path>`.","Run the project's init/bootstrap command to scaffold `_bmad/config.toml` and the skill `customize.toml`.","Check that the working directory or `--project-root` points at the project that owns the `_bmad` folder.","If the file genuinely should be optional for your flow, call `load_toml(path)` without `required=True` (or adjust the caller)."],"exampleFix":"# before: load_toml(Path('_bmad/config.toml'), required=True) -> file absent\n# fix: create the required config\nmkdir -p _bmad && cat > _bmad/config.toml <<'EOF'\n[project]\nname = \"my-project\"\nEOF","handlingStrategy":"validation","validationCode":"from pathlib import Path\npath = Path('_bmad/config.toml')\nassert path.is_file(), f'required TOML file not found: {path}'\nload_toml(path, required=True)","typeGuard":"def required_toml_present(path) -> bool:\n    return Path(path).is_file()","tryCatchPattern":"from config_utils import ConfigError\ntry:\n    load_toml(path, required=True)\nexcept ConfigError as e:\n    print(f\"error: {e}\", file=sys.stderr); sys.exit(2)","preventionTips":["Run the project's init step to scaffold required config before any render.","Always run tools from the project root that owns _bmad.","In CI, assert _bmad/config.toml exists in a pre-check before invoking tools."],"tags":["toml","config","filesystem","missing-file","bmad"],"backgroundTag":null,"analyzedSha":"b70486b9bdcb0a404d329e2a763b57964e7f1360","analyzedAt":"2026-08-13T01:21:12.247Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}