astrid-runtime/astrid · error

local capsule source {source:?} is not a regular file

Error message

local capsule source {source:?} is not a regular file

What it means

Once the capsule path is verified to be inside the authenticated root, its filesystem metadata is checked; if the target is not a regular file (directory, socket, fifo, device), resolve_local_capsule_archive rejects it. Capsule members must be regular archive files.

Source

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

        .components()
        .any(|component| matches!(component, Component::ParentDir))
    {
        bail!("local capsule source {source:?} escapes the authenticated Distro.toml directory");
    }

    let canonical_root = root
        .canonicalize()
        .with_context(|| format!("failed to resolve Distro.toml directory {}", root.display()))?;
    let canonical_path = candidate
        .canonicalize()
        .with_context(|| format!("failed to resolve local capsule source {source:?}"))?;
    if !canonical_path.starts_with(&canonical_root) {
        bail!("local capsule source {source:?} escapes the authenticated Distro.toml directory");
    }
    let metadata = std::fs::metadata(&canonical_path)
        .with_context(|| format!("failed to stat local capsule source {source:?}"))?;
    if !metadata.is_file() {
        bail!("local capsule source {source:?} is not a regular file");
    }
    if metadata.len() > MAX_MEMBER_BYTES {
        bail!(
            "local capsule source {source:?} is {} bytes, exceeding the \
             {MAX_MEMBER_BYTES}-byte member limit",
            metadata.len()
        );
    }

    Ok(Some(canonical_path))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn resolves_relative_member_from_manifest_parent() {

View on GitHub (pinned to affd8760f4)

Solutions

1. Point the source at the actual capsule archive file, not a directory
2. Build the capsule first so the regular file exists at the referenced path
3. Verify with `ls -l` that the referenced path is a regular file

Example fix

// before
source = "capsules/core"          # a directory
// after
source = "capsules/core.capsule"  # the archive file

let md = std::fs::metadata(capsule_path)?;
if !md.is_file() {
    anyhow::bail!("capsule source must be a regular file");
}

When it happens

Trigger: The source path in Distro.toml points to a directory or special file instead of a .capsule archive; a dangling/odd symlink resolves to a non-file.

Common situations: Typo in the source path resolving to a directory; creating a capsule directory where the file was expected; build output not yet produced leaving a placeholder.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• capsule materialization destination is not a directory
• capsule materialization destination already exists
• legacy capsule directory {id} does not match manifest id {}
• no Capsule.toml in {} — run `astrid capsule check` from a ca
• Capsule '{name}' is not installed.

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