astrid-runtime/astrid · error

workspace capsule component must be relative: {}

Error message

workspace capsule component must be relative: {}

What it means

This error means a component path in the workspace capsule's manifest was absolute, but workspace capsules are required to reference their components relative to the capsule's directory inside the workspace state dir. The library throws it while resolving workspace capsule components to guarantee all component files stay contained within the workspace capsule's own subtree (path-escape protection). Absolute paths are rejected rather than resolved to prevent capsules from pointing at arbitrary filesystem locations.

Source

Thrown at crates/astrid-kernel/src/lib.rs:1463

                .map_err(|error| {
                    anyhow::anyhow!("workspace capsule tree contains an unsafe redirect: {error}")
                })?;
        }
        Ok(())
    }

    #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
    fn verify_workspace_component_paths(
        &self,
        dir: &Path,
        manifest: &astrid_capsule_types::manifest::CapsuleManifest,
    ) -> anyhow::Result<()> {
        let Ok(capsule_relative) = dir.strip_prefix(self.workspace_selection.state_dir()) else {
            return Ok(());
        };
        for component in &manifest.components {
            if component.path.is_absolute() {
                anyhow::bail!(
                    "workspace capsule component must be relative: {}",
                    component.path.display()
                );
            }
            self.workspace_selection
                .resolve_file(capsule_relative.join(&component.path))
                .map_err(|error| {
                    anyhow::anyhow!(
                        "workspace capsule component path is unsafe ({}): {error}",
                        component.path.display()
                    )
                })?;
        }
        Ok(())
    }

    /// Verify an installed capsule against the authority source selected by
    /// this runtime. Native daemon loads use the packed System catalog; the

View on GitHub (pinned to affd8760f4)

Solutions

1. Edit Capsule.toml so every [[components]] path is relative to the capsule directory (e.g. "wasm/module.wasm" instead of "/home/user/.../module.wasm")
2. If the path was generated, fix the generator/script to emit paths relative to the capsule root
3. Verify with a quick check: no component path should start with "/" (or a Windows drive letter) and no path should contain ".." escaping the capsule dir
4. Regenerate or repackage the capsule so the manifest is rewritten with relative paths

Example fix

# before (Capsule.toml)
[[components]]
path = "/home/alice/build/capsule.wasm"

# after
[[components]]
path = "build/capsule.wasm"

for c in &manifest.components {
    if c.path.is_absolute() {
        return Err(format!("component path must be relative: {}", c.path.display()));
    }
}

match result {
    Err(e) if e.to_string().contains("must be relative") => {
        // fix Capsule.toml component paths; no retry will help
    }
    other => other?,
}

When it happens

Trigger: Resolving a workspace capsule (the code path that strips self.workspace_selection.state_dir() as the capsule dir prefix) when any entry in manifest.components has an is_absolute() path — e.g. a component declared as path = "/abs/path/to/file" or path = "C:\\..." in Capsule.toml.

Common situations: Hand-editing Capsule.toml and pasting an absolute path; a generator or script emitting absolute paths derived from the authoring machine; moving a capsule between machines where paths were recorded absolutely; copying an example config that used a machine-specific absolute path.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• capsule source is neither a directory nor a regular file: {}
• invalid value for {capsule_id}.{key}: expected one of {}, go
• empty archive path
• unsafe archive path '{path}'
• signed Distro member '{}' must resolve to a prebuilt .capsul

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