github/spec-kit · error · BundlerError

Downloaded artifact for bundle '{entry_id}' from {_source_de

Error message

Downloaded artifact for bundle '{entry_id}' from {_source_desc} is not a valid bundle.

What it means

This is a defensive invariant guard: after Spec Kit writes the downloaded ZIP to a temporary file, the local manifest reader should never return None. None normally means the file does not exist, so this error marks an impossible/racy state rather than a normal user-input failure.

Source

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

                artifact = Path(tmp) / "bundle.zip"
                artifact.write_bytes(raw)
                # Wrap ZIP parsing so any failure (BadZipFile, missing
                # bundle.yml, etc.) references the source URL rather than the
                # opaque temporary path, consistent with the download-error
                # handling above.
                try:
                    manifest = _local_manifest_source(str(artifact))
                except Exception as exc:  # noqa: BLE001
                    raise BundlerError(
                        f"Downloaded artifact for bundle '{entry_id}' from "
                        f"{_source_desc} is not a valid bundle: {exc}"
                    ) from exc
                # _local_manifest_source returns None only when the file does
                # not exist; since we just wrote *artifact* that cannot happen
                # here.  The explicit guard ensures callers never receive None
                # 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}"

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Retry the bundle command once to rule out a transient temporary-directory race.
2. Check TEMP/TMP permissions and free disk space if it recurs.
3. Capture the exact command, catalog entry, and environment and report it as a Spec Kit defect because this branch is designed to be unreachable.

except BundlerError as exc:
    if "is not a valid bundle." in str(exc) and str(exc).endswith("bundle."):
        collect_diagnostics_and_report_bug()
    else:
        raise

When it happens

Trigger: The temporary `bundle.zip` disappears or reports non-existence between write_bytes and _local_manifest_source, or internal code/monkeypatching breaks the documented contract. Normal malformed ZIP errors take the preceding exception branch instead.

Common situations: Essentially not reached in normal use. A hypothetical trigger is an external process or antivirus removing the temporary file, a broken temp filesystem, or patched internal functions.

Related errors

• Downloaded artifact for bundle '{entry_id}' from {_source_de
• Artifact '{candidate}' does not contain a bundle.yml.
• Could not read bundle.yml inside '{candidate}': {exc}
• Invalid YAML in bundle.yml inside '{candidate}': {exc}
• Refusing to download {label}: URL is malformed: {url}

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