github/spec-kit · error · BundlerError

Failed to parse downloaded bundle '{entry_id}' from {_source

Error message

Failed to parse downloaded bundle '{entry_id}' from {_source_desc}: {exc}

What it means

This is the final safety net while converting successfully parsed YAML into a BundleManifest. Exceptions that are already BundlerError or yaml.YAMLError are re-raised with their clearer messages; anything unexpected is wrapped here with its cause attached. Seeing it usually indicates an unusual parser/model failure or a Spec Kit bug rather than ordinary invalid YAML.

Source

Thrown at src/specify_cli/commands/bundle/__init__.py:1051

                # and silently degrade instead of raising a clear error.
                if manifest is None:
                    raise BundlerError(
                        f"Downloaded artifact for bundle '{entry_id}' from "
                        f"{_source_desc} is not a valid bundle."
                    )
                return manifest

        data = _yaml.safe_load(io.BytesIO(raw))
        return BundleManifest.from_dict(data)
    except BundlerError:
        raise
    except _yaml.YAMLError as exc:
        raise BundlerError(
            f"Downloaded content for bundle '{entry_id}' from {_source_desc} "
            f"is not valid YAML: {exc}"
        ) from exc
    except Exception as exc:  # noqa: BLE001
        raise BundlerError(
            f"Failed to parse downloaded bundle '{entry_id}' from "
            f"{_source_desc}: {exc}"
        ) from exc


def _validate_manifest_structure(manifest, *, source: str) -> None:
    """Reject a malformed manifest before any project mutation can occur."""
    from ...bundler.services.validator import validate_manifest

    report = validate_manifest(manifest)
    if report.ok:
        return
    raise BundlerError(
        f"{source} contains an invalid bundle manifest:\n  - "
        + "\n  - ".join(report.errors)
    )

View on GitHub (pinned to bf88c9f9a8)

Solutions

Inspect the chained `__cause__` and the downloaded YAML at the URL named in the message.
Reduce bundle.yml to the minimal fields (schema_version, bundle metadata, requires.speckit_version) and re-add sections until the failing construct is found.
Validate the same file locally with BundleManifest.from_dict to see whether the failure is reproducible outside downloading.
If a minimal valid-looking manifest still triggers it, report a Spec Kit bug with the YAML and traceback.

Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
import yaml

def manifest_is_plain_mapping(path: Path) -> bool:
    data = yaml.safe_load(path.read_text(encoding="utf-8"))
    return isinstance(data, dict) and isinstance(data.get("bundle"), dict)

Try / catch

except BundlerError as exc:
    if "Failed to parse downloaded bundle" in str(exc):
        log_yaml_and_cause(exc.__cause__)
        report_minimal_reproduction()
    else:
        raise

Prevention

Keep manifest values as plain YAML scalars, mappings, and lists.
Test manifests with BundleManifest.from_dict before publishing.
Preserve chained causes in logs so unexpected parser errors can be classified.

When it happens

Trigger: `BundleManifest.from_dict(data)` raises a non-BundlerError exception, such as an unexpected TypeError while converting a YAML value, after `_yaml.safe_load` has already succeeded.

Common situations: Rare. Potential contexts are an exotic YAML value that reaches an unguarded conversion, a Python/library version incompatibility, or an internal regression in manifest construction.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/f9f8126f0ab754ed. Report an issue: GitHub.