{"record":{"id":"38f7bf911127fe80","repo":"github/spec-kit","slug":"malformed-catalog-config-at-config-path-catalo","errorCode":null,"errorMessage":"Malformed catalog config at {config_path}: 'catalogs' must be a list, got {type(catalogs).__name__}.","messagePattern":"Malformed catalog config at (.+?): 'catalogs' must be a list, got (.+?)\\.","errorType":"exception","errorClass":"BundlerError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/bundler/models/catalog.py","lineNumber":312,"sourceCode":"            f\"Unsupported catalog config schema version \"\n            f\"'{str(schema_version).strip()}' at {config_path}; this Spec Kit \"\n            f\"understands version {CONFIG_SCHEMA_VERSION}. The file may have been \"\n            \"written by a newer version or is corrupt.\"\n        )\n    catalogs = data.get(\"catalogs\")\n    if catalogs is None:\n        return\n    if not isinstance(catalogs, list):\n        # Treat only an absent/``None`` ``catalogs`` as \"nothing to merge\"; any\n        # other non-list value (``catalogs: 5``, ``false``, ``0``, ``''``,\n        # ``{}``) is a malformed config and must raise, not be silently skipped\n        # by a falsy check. Otherwise a truthy scalar would raise a raw\n        # ``TypeError: 'int' object is not iterable`` from the loop below, while\n        # falsy non-lists would be swallowed. Report the same actionable\n        # BundlerError the sibling reader of this file raises\n        # (commands_impl/catalog_config.py) so both readers of\n        # bundle-catalogs.yml agree. An empty list stays valid (loop is a no-op).\n        raise BundlerError(\n            f\"Malformed catalog config at {config_path}: 'catalogs' must be a \"\n            f\"list, got {type(catalogs).__name__}.\"\n        )\n    for raw in catalogs:\n        src = CatalogSource.from_dict(raw, scope)\n        by_id[src.id] = src\n","sourceCodeStart":294,"sourceCodeEnd":319,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/bundler/models/catalog.py#L294-L319","documentation":"Raised when a bundle-catalogs.yml has a top-level mapping but the 'catalogs' key holds a non-list value (e.g. 'catalogs: 5', 'catalogs: false', 'catalogs: {}', or a string). Only an absent or null 'catalogs' is treated as 'nothing to merge'; every other non-list is malformed. Without this guard, a truthy scalar would crash later with a raw TypeError while falsy non-lists would be silently swallowed.","triggerScenarios":"A config file with 'catalogs:' followed by a scalar, mapping, or boolean instead of a YAML sequence is read via _merge_config during bundle search/install. An empty list (catalogs: []) is valid and merges nothing.","commonSituations":"Writing 'catalogs:' with an inline flow mapping '{...}' instead of a list; forgetting the '-' bullet so a single catalog becomes a mapping; setting 'catalogs: false' while experimenting; hand-merging two config files incorrectly.","solutions":["Change the 'catalogs' value to a YAML list of catalog mappings (each entry starting with '- ').","If you meant no catalogs, remove the key entirely or set it to null — do not use false/0/''/{}.","Leave 'catalogs: []' if you want an explicitly empty list."],"exampleFix":"# before (bundle-catalogs.yml)\ncatalogs:\n  id: my-catalog\n  url: https://example.com/catalog.yml\n\n# after\ncatalogs:\n  - id: my-catalog\n    url: https://example.com/catalog.yml","handlingStrategy":"validation","validationCode":"import yaml\nfrom pathlib import Path\n\ndef catalogs_key_is_list(path: Path) -> bool:\n    data = yaml.safe_load(path.read_text()) or {}\n    catalogs = data.get(\"catalogs\")\n    return catalogs is None or isinstance(catalogs, list)","typeGuard":"def is_optional_list(v: object) -> bool:\n    return v is None or isinstance(v, list)","tryCatchPattern":"try:\n    resolve_catalogs(...)\nexcept BundlerError as e:\n    if \"'catalogs' must be a list\" in str(e):\n        # fix the YAML sequence shape, then retry\n        ...","preventionTips":["Every catalog entry under 'catalogs:' must start with '- '.","Use 'catalogs: []' or omit the key for empty — never false/0/''/{}.","Validate with a JSON-Schema description of bundle-catalogs.yml in CI."],"tags":["bundler","yaml","catalog","validation","config"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}