astrid-runtime/astrid · error

--offline: capsule '{}' has a network/GitHub source '{}' — r

Error message

--offline: capsule '{}' has a network/GitHub source '{}' — refusing to fetch. Use a .shuttle archive for a self-contained offline install.

What it means

When --offline is passed, refuse_offline_network_sources pre-checks all selected capsules and refuses the install if any capsule's source is a network/GitHub source. Offline installs must come from self-contained .shuttle archives; the CLI refuses to fetch.

Source

Thrown at crates/astrid-cli/src/commands/init.rs:680

/// Whether a capsule `source` would have to touch the network to install.
///
/// Only GitHub-backed shapes (`@org/repo`, `github.com/…`,
/// `https://github.com/…`) are network sources; everything else — including
/// a relative local path like `capsules/cli.capsule` — installs straight
/// from disk. This is the predicate the `--offline` guard rejects on, so it
/// must NOT reject a bare relative path the way the old `starts_with('.')`
/// /`starts_with('/')` check wrongly did.
fn is_network_capsule_source(source: &str) -> bool {
    astrid_capsule_install::github_source::parse_github_source(source.trim()).is_some()
}

fn refuse_offline_network_sources(selected: &[DistroCapsule], offline: bool) -> anyhow::Result<()> {
    if !offline {
        return Ok(());
    }
    for cap in selected {
        if is_network_capsule_source(&cap.source) {
            bail!(
                "--offline: capsule '{}' has a network/GitHub source '{}' — \
                 refusing to fetch. Use a .shuttle archive for a self-contained \
                 offline install.",
                cap.name,
                cap.source
            );
        }
    }
    Ok(())
}

/// Install each selected capsule with a progress bar.
///
/// Under `offline`, a capsule whose source is GitHub-backed is a hard
/// error — the `--offline` contract forbids any network, and a remote
/// `@org/repo` capsule in a local `Distro.toml` would otherwise silently
/// fetch from GitHub. A local path (relative or absolute) installs from
/// disk and is allowed. (A fully self-contained offline install uses a

View on GitHub (pinned to affd8760f4)

Solutions

1. Use a .shuttle archive distro, which bundles all capsules for a self-contained offline install.
2. Drop --offline if network access is actually available and you want the GitHub-sourced distro.
3. Pre-download the capsules and repackage them into a local .shuttle archive.

Example fix

// before
astrid init @acme/distro --offline
// after
astrid init ./acme-distro.shuttle --offline

if offline && capsules.iter().any(|c| is_network_capsule_source(&c.source)) {
    eprintln!("offline install requires a .shuttle archive");
    std::process::exit(2);
}

match refuse_offline_network_sources(&selected, offline) {
    Ok(()) => install(),
    Err(e) => eprintln!("{e:#}"),
}

When it happens

Trigger: install_capsules_with_resume called with offline=true and at least one selected DistroCapsule whose source passes is_network_capsule_source (a GitHub/network source).

Common situations: Running `astrid init --offline` against a GitHub-hosted distro during an outage or air-gapped environment; assuming --offline works with any distro.

Related errors

• all {total} capsule install(s) failed — not writing Distro.l
• --offline: '{source}' is not a local file and network fetch
• --offline: signed source member {file_name} is not local and
• Source path does not exist: {source}
• Failed to auto-build capsule from Cargo project.

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/996c846d0ae0ab4f. Report an issue: GitHub.