{"record":{"id":"a78019857c095ca7","repo":"bmad-code-org/BMAD-METHOD","slug":"failed-to-parse-path-error","errorCode":null,"errorMessage":"failed to parse {path}: {error}","messagePattern":"failed to parse (.+?): (.+?)","errorType":"exception","errorClass":"ConfigError","httpStatus":null,"severity":"error","filePath":"src/scripts/config_utils.py","lineNumber":29,"sourceCode":"    \"\"\"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\n    for candidate in _KEYED_MERGE_FIELDS:\n        if all(candidate in item for item in items):\n            for item in items:\n                value = item[candidate]\n                if not isinstance(value, str):\n                    raise ConfigError(\n                        f\"keyed array identifier `{candidate}` must be a string, \"\n                        f\"got {type(value).__name__}\"","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/bmad-code-org/BMAD-METHOD/blob/b70486b9bdcb0a404d329e2a763b57964e7f1360/src/scripts/config_utils.py#L11-L47","documentation":"`load_toml` catches `tomllib.TOMLDecodeError` and re-raises it as `ConfigError` with the file path and the underlying parse error. It means the TOML file was read from disk but its syntax is invalid — unclosed string, duplicate keys, a bare value, an unterminated table header, a malformed array, or a non-TOML file (YAML/JSON) that was placed there by mistake.","triggerScenarios":"A hand-edited `_bmad/config.toml` with a syntax slip (`name = BMAD` instead of `name = \"BMAD\"`); a YAML or JSON file saved with a `.toml` extension; a merge conflict marker left in the file; an unterminated multiline string.","commonSituations":"Editing config without a TOML-aware editor; copying a snippet from docs that used a different config language; unresolved `<<<<<<<` conflict markers after a git merge.","solutions":["Read the full error text after the colon — it includes the line/column of the parse failure.","Open the file at that line and fix the syntax (quote string values, close brackets, deduplicate keys).","Validate with a TOML linter: `python -c \"import tomllib;tomllib.load(open('<path>','rb'))\"`.","If the file is actually YAML/JSON, convert it to TOML or move it to the correct extension/layer."],"exampleFix":"# before (config.toml)\n[project]\nname = BMAD          # bare value -> TOMLDecodeError\nversion = 1.0.       # trailing dot\n\n# after\n[project]\nname = \"BMAD\"\nversion = \"1.0\"","handlingStrategy":"try-catch","validationCode":"import tomllib\ntry:\n    tomllib.load(open(path,'rb'))\nexcept tomllib.TOMLDecodeError as e:\n    raise SystemExit(f'TOML syntax error: {e}')","typeGuard":null,"tryCatchPattern":"try:\n    load_toml(path, required=required)\nexcept ConfigError as e:\n    print(f\"error: {e}\", file=sys.stderr); sys.exit(2)","preventionTips":["Edit TOML with a TOML-aware editor that flags syntax errors live.","Quote string values; never leave conflict markers in config.","Run python -m tomllib (or a linter) over config in CI."],"tags":["toml","config","syntax","parsing","bmad"],"backgroundTag":null,"analyzedSha":"b70486b9bdcb0a404d329e2a763b57964e7f1360","analyzedAt":"2026-08-13T01:21:12.247Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}