github/spec-kit · error · BundlerError

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

Error message

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

What it means

An extension component is not present in the bundle artifact's bundled/ tree, so installing it requires the network, but the bundler was run with allow_network=False (--offline). The message offers both remedies: re-run online or pre-install with `specify extension add <id>`.

Source

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

        bundled = _locate_bundled_extension(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(
                "Extension",
                component.id,
                component.version,
                _bundled_manifest_version(bundled / "extension.yml", "extension"),
            )
            self._manager.install_from_directory(
                bundled, speckit_version, priority=priority, force=force
            )
            return

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

        from ...extensions import ExtensionCatalog

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

View on GitHub (pinned to bf88c9f9a8)

Solutions

Pre-install the extension online once: `specify extension add <id>`, then run the offline bundle install.
Drop --offline for this bundle if network is permitted.
Rebuild the bundle with the extension vendored into bundled/ for permanently offline targets.

Example fix

specify extension add my-extension   # once, with network
specify bundle install my-bundle-1.0.0.zip --offline

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" / "extensions" / component_id
    return bundled.is_dir() or extension_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", "extension", "add", extract_id(str(exc))], check=True)
        install_bundle(project_root, plan, installer, allow_network=False)

Prevention

Pre-stage extensions with `specify extension add <id>` before offline bundle installs.
Build offline-targeted bundles with extensions vendored under bundled/.
Exercise the full offline install path in CI against a clean project.

When it happens

Trigger: `specify bundle install <artifact> --offline` where the artifact does not vendor the extension directory, reaching the `if not self._allow_network` branch in _ExtensionKindManager.install at primitives.py:270.

Common situations: Air-gapped CI installs of bundles that pin catalog extensions without vendoring them; --offline used to make installs deterministic but the bundle expects remote fetch.

Related errors

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