local capsule source

Error message

local capsule source {source:?} requires a local authenticated Distro.toml; remote manifests cannot resolve relative members

What it means

resolve_local_capsule_archive only handles local capsule sources when a local, authenticated Distro.toml manifest path is supplied. If the source is local but manifest_path is None (e.g. the manifest came from a remote registry), relative member paths cannot be anchored anywhere, so the function fails closed instead of guessing a root directory.

Solutions

Use the local authenticated Distro.toml (pass its path so relative members can be resolved)
Replace the local capsule source with a registry-published reference in remote manifests
Restructure the manifest so remote entries and local capsule members are not mixed

Example fix

// before
resolve_local_capsule_archive(source, None)?;
// after
resolve_local_capsule_archive(source, Some(&local_distro_toml_path))?;

Defensive patterns

Strategy: validation

Validate before calling

if is_local_capsule_source(source) && manifest_path.is_none() {
    anyhow::bail!("local capsule source requires a local Distro.toml path");
}

Prevention

Always supply the local authenticated Distro.toml path when resolving local capsule sources
Keep remote manifests free of local relative capsule references
Resolve sources only after loading the manifest from disk

When it happens

Trigger: A Distro.toml fetched from a remote source references a local capsule `source = "..."` entry; resolve_local_capsule_archive is invoked without a manifest path while is_local_capsule_source(source) is true.

Common situations: Sealing/publishing a manifest that mixes remote registry entries with local relative capsule paths; running against a fetched manifest outside its project directory.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

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/335455fa30cd38b5. Report an issue: GitHub.

Appendix: source

Thrown at crates/astrid-cli/src/commands/distro/local_source.rs:49

        )
    })?;
    Ok(current_dir.join(manifest_path))
}

/// Resolve a local `.capsule` member against the authenticated manifest.
///
/// `Ok(None)` means the source belongs to the caller's remote resolver.
/// The returned path is canonicalized so the subsequent copy and hash cover
/// the same filesystem object that passed containment checks.
pub(crate) fn resolve_local_capsule_archive(
    source: &str,
    manifest_path: Option<&Path>,
) -> anyhow::Result<Option<PathBuf>> {
    if !is_local_capsule_source(source) {
        return Ok(None);
    }
    let Some(manifest_path) = manifest_path else {
        bail!(
            "local capsule source {source:?} requires a local authenticated Distro.toml; \
             remote manifests cannot resolve relative members"
        );
    };

    let root = manifest_path
        .parent()
        .ok_or_else(|| anyhow::anyhow!("Distro.toml has no parent directory"))?;
    let source_path = Path::new(source);
    let candidate = if source_path.is_absolute() {
        source_path.to_path_buf()
    } else {
        root.join(source_path)
    };
    if source_path
        .components()
        .any(|component| matches!(component, Component::ParentDir))
    {

View on GitHub (pinned to affd8760f4)