{"record":{"id":"d27cae6cd5849a94","repo":"github/spec-kit","slug":"could-not-read-bundle-yml-inside-candidate-e","errorCode":null,"errorMessage":"Could not read bundle.yml inside '{candidate}': {exc}","messagePattern":"Could not read bundle\\.yml inside '(.+?)': (.+?)","errorType":"exception","errorClass":"BundlerError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/commands/bundle/__init__.py","lineNumber":801,"sourceCode":"                raise BundlerError(\n                    f\"Artifact '{candidate}' does not contain a bundle.yml.\"\n                ) from exc\n            raw = read_zip_member_limited(\n                archive,\n                \"bundle.yml\",\n                error_type=BundlerError,\n                label=\"bundle manifest\",\n            )\n        # The bounded-zip helpers above keep archive failures inside the\n        # BundlerError contract, but the manifest bytes need the same\n        # treatment as yamlio.load_yaml: decode as UTF-8 explicitly —\n        # feeding PyYAML the byte stream would let its Reader auto-detect\n        # a UTF-16 BOM and accept a manifest the directory and bundle.yml\n        # sources reject.\n        try:\n            text = raw.decode(\"utf-8\")\n        except UnicodeError as exc:\n            raise BundlerError(\n                f\"Could not read bundle.yml inside '{candidate}': {exc}\"\n            ) from exc\n        try:\n            data = _yaml.safe_load(text)\n        except _yaml.YAMLError as exc:\n            # The sibling directory/bundle.yml branches reach YAML through\n            # load_yaml(), which turns a parse failure into a BundlerError. This\n            # branch parses inline, so without this it raises a raw YAMLError --\n            # neither a ValueError nor an OSError -- which escapes\n            # bundle_install()'s `except BundlerError` as a traceback.\n            raise BundlerError(\n                f\"Invalid YAML in bundle.yml inside '{candidate}': {exc}\"\n            ) from exc\n        return BundleManifest.from_dict(data)\n\n    if candidate.name == \"bundle.yml\" or candidate.suffix in (\".yml\", \".yaml\"):\n        return BundleManifest.from_file(candidate)\n","sourceCodeStart":783,"sourceCodeEnd":819,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/commands/bundle/__init__.py#L783-L819","documentation":"After extracting the raw bundle.yml bytes from a zip, the CLI decodes them explicitly as UTF-8 (mirroring yamlio.load_yaml). A UnicodeError here means the manifest is not UTF-8 — commonly a UTF-16 file with a BOM, which PyYAML's auto-detecting Reader would otherwise silently accept, creating an inconsistency with the directory and file sources that both require UTF-8.","triggerScenarios":"A bundle.yml saved as UTF-16 (e.g. authored in Windows PowerShell redirection or Notepad defaults) and zipped into the artifact; passed to specify bundle install ./bundle.zip.","commonSituations":"Windows authoring tools writing UTF-16; build scripts converting encodings; manifests with non-ASCII author names saved in the wrong encoding.","solutions":["Re-encode the manifest to UTF-8 (without BOM): iconv -f UTF-16 -t UTF-8 bundle.yml, then re-zip.","Configure your editor to save YAML as UTF-8.","Fix the packaging pipeline that produced the artifact."],"exampleFix":"# before\nGet-Content bundle.yml | Out-File bundle.yml   # PowerShell: UTF-16\n\n# after (UTF-8, no BOM)\niconv -f UTF-16 -t UTF-8 bundle.yml > bundle.utf8.yml && mv bundle.utf8.yml bundle.yml","handlingStrategy":"validation","validationCode":"raw = b'...'  # bytes from the zip member\ntry:\n    text = raw.decode(\"utf-8\")\nexcept UnicodeError:\n    raise SystemExit(\"bundle.yml must be UTF-8 (found BOM/UTF-16?)\")","typeGuard":"def is_utf8_manifest(raw: bytes) -> bool:\n    try:\n        raw.decode(\"utf-8\")\n        return True\n    except UnicodeError:\n        return False","tryCatchPattern":"try:\n    manifest = _local_manifest_source(Path(\"bundle.zip\"))\nexcept BundlerError as exc:\n    if \"Could not read bundle.yml inside\" in str(exc):\n        # re-encode manifest to UTF-8 without BOM and re-zip\n        ...","preventionTips":["Save YAML as UTF-8 without BOM, especially on Windows.","Add an editorconfig (.editorconfig charset = utf-8) to bundle repos."],"tags":["bundler","encoding","utf-8","zip"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}