astrid-runtime/astrid · error

Failed to add capsule view: {e}

Error message

Failed to add capsule view: {e}

What it means

Thrown when registering an existing system-runtime capsule view fails: `registry.register_existing(&id, &wasm_hash, principal)` returned an error while trying to attach a known system runtime capsule (matched by id and wasm hash) to a principal. The registry's error is wrapped as 'Failed to add capsule view'.

Source

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

        if system_runtime && !manifest.mcp_servers.is_empty() {
            anyhow::bail!(
                "system-resident capsule '{id}' cannot host principal-bearing stdio MCP servers"
            );
        }
        self.verify_workspace_capsule_tree(&runtime_dir)?;

        // Mutable runtimes are authority-scoped. A principal always receives a
        // fresh runtime for its immutable UID; only an explicitly classified
        // SystemResident service may attach another view to one runtime.
        {
            let mut registry = self.capsules.write().await;
            if registry.get_for(principal, &id).is_some() {
                return Ok(());
            }
            if system_runtime && registry.contains_system_runtime(&id, &wasm_hash) {
                registry
                    .register_existing(&id, &wasm_hash, principal)
                    .map_err(|e| anyhow::anyhow!("Failed to add capsule view: {e}"))?;
                if let Some(capsule) = registry.get_for(principal, &id) {
                    capsule.resume_for(principal);
                }
                return Ok(());
            }
        }
        if system_runtime && principal != &PrincipalId::default() {
            anyhow::bail!(
                "system-resident capsule '{id}' must be created by the operator/default view before dependents attach"
            );
        }
        // System residency is an operator/admin classification, not a host
        // path ancestry claim. The source directory is a disposable
        // materialization of the durable package registry; `system_capsules`
        // is the authenticated admission set and the installed authority
        // receipt was verified above.

        let principal_uid = self.runtime_principal_uid(system_runtime, principal, &id)?;

View on GitHub (pinned to affd8760f4)

Solutions

1. Verify the wasm_hash matches the registered system runtime for that capsule id.
2. Rebuild/re-sync the registry state if it is inconsistent with installed runtimes.
3. Inspect the wrapped `{e}` source from register_existing for the concrete rejection reason.
4. Ensure the capsule id is not colliding with another capsule carrying a different hash.

// confirm hash matches the registered system runtime before register_existing
let known = registry.contains_system_runtime(&id, &wasm_hash);
anyhow::ensure!(known, "wasm hash does not match registered system runtime for {id}");

match ensure_capsule_view(&mut registry, principal, &id, &wasm_hash, system_runtime) {
    Err(e) if e.to_string().contains("Failed to add capsule view") => {
        // inspect inner register_existing error; re-sync registry or rebuild runtime
    }
    other => other,
}

When it happens

Trigger: Calling the capsule-ensure path for a principal when the capsule is already known system runtime, but register_existing rejects the registration — e.g. hash mismatch with the registered system runtime, conflicting existing registration, or registry backend error.

Common situations: Kernel/runtime upgrade changed the wasm hash so it no longer matches the stored system runtime; corrupted registry state; duplicate id with a different hash.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• durable capsule removal is unavailable on portable hosts
• WASM capsule has no BLAKE3 hash in meta.json
• unexpected response from kernel: {other:?}
• kernel refused storage mount: {error}
• publish WASM into the system content catalog

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