--offline: '{source}' is not a local file and network fetch

Error message

--offline: '{source}' is not a local file and network fetch is forbidden (use a Distro.toml path or a .shuttle archive)

What it means

fetch_manifest_bytes enforces the --offline flag: when the Distro source is not a local file that can be read directly, and offline mode is active, any network fetch is forbidden and this error is thrown. It tells the user to supply a local Distro.toml path or a local .shuttle archive instead.

Source

Thrown at crates/astrid-cli/src/commands/init_signed_source.rs:162

        resolved.push(member);
    }
    Ok(resolved)
}

/// Resolve a distro source to its exact bytes and parse those bytes once.
async fn fetch_manifest_bytes(
    source: &str,
    offline: bool,
) -> anyhow::Result<(Vec<u8>, DistroManifest)> {
    let path = Path::new(source);
    if path.exists() && path.is_file() {
        let bytes =
            std::fs::read(path).with_context(|| format!("failed to read {}", path.display()))?;
        return parse_manifest_bytes(bytes);
    }

    if offline {
        bail!(
            "--offline: '{source}' is not a local file and network fetch is forbidden \
             (use a Distro.toml path or a .shuttle archive)"
        );
    }

    let url = super::resolve_distro_url(source)?;
    eprintln!("Fetching Distro.toml...");
    let bytes = fetch_url_bytes(&url, "Distro.toml", 1024 * 1024).await?;
    parse_manifest_bytes(bytes)
}

fn parse_manifest_bytes(bytes: Vec<u8>) -> anyhow::Result<(Vec<u8>, DistroManifest)> {
    anyhow::ensure!(bytes.len() <= 1024 * 1024, "Distro.toml exceeds 1 MB limit");
    let content = std::str::from_utf8(&bytes).context("Distro.toml is not valid UTF-8")?;
    let manifest = parse_manifest(content)?;
    Ok((bytes, manifest))
}

View on GitHub (pinned to affd8760f4)

Solutions

Provide a local Distro.toml file path or a local .shuttle archive as the source.
Pre-download the Distro manifest while online, then re-run with --offline pointing at the local copy.
If network access is actually available and permitted, drop the --offline flag.

Example fix

// before
astrid init --offline https://distro.example.com/Distro.toml

// after
wget https://distro.example.com/Distro.toml -O ./Distro.toml
astrid init --offline ./Distro.toml

Defensive patterns

Strategy: validation

Validate before calling

# confirm source is a local file when using --offline
SRC="./Distro.toml"
[[ -f "$SRC" ]] || { echo "--offline requires a local Distro.toml or .shuttle archive"; exit 1; }
astrid init --offline "$SRC"

Try / catch

// shell
if ! astrid init --offline "$SRC" 2>err.log; then
  grep -q 'network fetch is forbidden' err.log && echo "pre-download the manifest first"
fi

Prevention

Pre-download Distro.toml/.shuttle archives before going offline.
Double-check the source path spelling so local files are actually found.
In CI, cache the distro manifest and reference the cached path with --offline.

When it happens

Trigger: Running with --offline while `source` is a URL or registry identifier (not an existing local path); prepare_distro_source/fetch_signed_manifest call fetch_manifest_bytes, which skips the local-read branch and hits the `if offline` bail.

Common situations: CI or air-gapped machines running `astrid init --offline <url>`; typo in a local path so it isn't found as a file, causing a network fetch attempt that offline mode blocks.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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