github/spec-kit · error · BundlerError

Preset '{component.id}' is not bundled and network access is

Error message

Preset '{component.id}' is not bundled and network access is disabled; re-run without --offline or install it first with 'specify preset add {component.id}'.

What it means

A bundle install needs to fetch a preset from the network because the preset is not bundled inside the artifact, but the bundler was constructed with allow_network=False (--offline). The error names both remedies: drop --offline, or pre-install the preset with `specify preset add <id>` so the install can proceed offline.

Source

Thrown at src/specify_cli/bundler/services/primitives.py:189

        bundled = _locate_bundled_preset(component.id)
        if bundled is not None:
            # Enforce the manifest pin against the bundled asset's own version,
            # mirroring the catalog path below (the bundled path previously
            # skipped the pin entirely).
            _assert_pinned_version(
                "Preset",
                component.id,
                component.version,
                _bundled_manifest_version(bundled / "preset.yml", "preset"),
            )
            self._manager.install_from_directory(
                bundled, speckit_version, priority, **({"force": True} if force else {})
            )
            return

        if not self._allow_network:
            raise BundlerError(
                f"Preset '{component.id}' is not bundled and network access is "
                f"disabled; re-run without --offline or install it first with "
                f"'specify preset add {component.id}'."
            )

        from ...presets import PresetCatalog

        catalog = PresetCatalog(self._root)
        info = catalog.get_pack_info(component.id)
        if not info:
            raise BundlerError(f"Preset '{component.id}' not found in any catalog.")
        if not info.get("_install_allowed", True):
            raise BundlerError(
                f"Preset '{component.id}' is from a discovery-only catalog; "
                "installation is not allowed."
            )
        _assert_pinned_version(
            "Preset", component.id, component.version, info.get("version")

View on GitHub (pinned to bf88c9f9a8)

Solutions

Pre-install the preset in the target project first: `specify preset add <id>` (online once), then re-run the offline bundle install.
Re-run the bundle install without --offline if network is acceptable.
For a permanently offline environment, rebuild the bundle so the preset is vendored into the artifact's bundled/ directory.

Example fix

specify preset add my-preset   # once, with network
specify bundle install my-bundle-1.0.0.zip --offline  # now succeeds

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def offline_ready(artifact_dir: Path, component_id: str) -> bool:
    bundled = artifact_dir / "bundled" / "presets" / component_id
    return bundled.is_dir() or preset_already_installed(project_root, component_id)

Try / catch

from specify_cli.bundler.core import BundlerError

try:
    install_bundle(project_root, plan, installer, allow_network=False)
except BundlerError as exc:
    if "network access is disabled" in str(exc):
        subprocess.run(["specify", "preset", "add", extract_id(str(exc))], check=True)
        install_bundle(project_root, plan, installer, allow_network=False)

Prevention

For offline environments, pre-install every catalog preset the bundle needs, or build bundles that vendor presets into bundled/.
Test `--offline` installs in CI with a clean project root to catch un-vendored components early.
Document which bundle components require network so operators can pre-stage them.

When it happens

Trigger: Running `specify bundle install <artifact> --offline` where the artifact's bundled/ tree does not contain the preset directory, so _PresetKindManager hits the `if not self._allow_network` branch at primitives.py:187.

Common situations: Air-gapped or CI environments using --offline with a bundle that only pins catalog presets without vendoring them; a bundle built from a manifest-only directory where components were expected to be fetched remotely.

Related errors

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