astrid-runtime/astrid · error

capsule {operation} '{}' exceeds or cannot prove its install

Error message

capsule {operation} '{}' exceeds or cannot prove its installed authority: {error:#}

What it means

When a capsule has no durable registry authority (published_capsule_snapshot returned None) and verify_registry_materialization did not bind it, capture_bound_materialization calls verify_installed_authority_for_runtime to prove the capsule's manifest does not exceed its installed authority. Any failure from that check is re-wrapped with this message naming the operation and capsule package name. The library throws it because running an unbound capsule outside the workspace portal is only allowed if its runtime manifest can be proven within the authority recorded at install time.

Source

Thrown at crates/astrid-kernel/src/capsule_materialization.rs:148

            )?;
            return Ok(Some(BoundMaterialization {
                snapshot,
                runtime_dir,
                manifest: bound_manifest,
            }));
        }
        if !self.verify_registry_materialization(dir, principal, manifest)? {
            if self.principal_store.is_some()
                && !dir.starts_with(self.workspace_selection.state_dir())
            {
                anyhow::bail!(
                    "capsule {operation} '{}' is outside the explicit workspace portal and \
                     has no durable registry authority",
                    manifest.package.name
                );
            }
            self.verify_installed_authority_for_runtime(dir, manifest).map_err(|error| {
                anyhow::anyhow!(
                    "capsule {operation} '{}' exceeds or cannot prove its installed authority: {error:#}",
                    manifest.package.name
                )
            })?;
        }
        Ok(None)
    }

    /// Repair a stale or missing cache generation from one exact snapshot.
    #[cfg(not(all(target_arch = "wasm32", target_os = "unknown")))]
    pub(crate) fn ensure_published_materialization(
        &self,
        target: &Path,
        principal: &astrid_core::principal::PrincipalId,
        manifest: &astrid_capsule_types::manifest::CapsuleManifest,
        snapshot: &astrid_storage::CapsulePackageSnapshot,
    ) -> anyhow::Result<astrid_capsule_types::manifest::CapsuleManifest> {
        self.repair_published_materialization(target, principal, manifest, snapshot)

View on GitHub (pinned to affd8760f4)

Solutions

1. Install/publish the capsule into the durable registry so published_capsule_snapshot can bind it, then retry the operation.
2. If the capsule is meant to be local, keep it inside the workspace portal state dir (dir must start with workspace_selection.state_dir()).
3. Reduce the manifest's requested capabilities to those approved in the installed authority.json, or re-approve/upgrade the authority and reinstall.
4. Inspect the inner {error:#} chain: fix the specific failure in verify_installed_authority_for_runtime (missing/corrupt authority.json, unreadable file, capability expansion mismatch) before retrying.

Example fix

// before: hand-edited manifest requesting unapproved capabilities
let bound = kernel.load_capsule(&dir, &principal, &manifest_with_new_caps)?;

// after: reinstall so authority covers the manifest capabilities
// $ astrid install ./my-capsule   # regenerates approved authority
let bound = kernel.load_capsule(&dir, &principal, &approved_manifest)?;

// Prove local authority before calling the API for an unbound capsule
fn can_prove_installed_authority(dir: &std::path::Path) -> Result<(), String> {
    let authority = std::fs::read(dir.join("authority.json"))
        .map_err(|e| format!("installed authority unreadable: {e}"))?;
    let manifest = std::fs::read_to_string(dir.join("Capsule.toml"))
        .map_err(|e| format!("manifest unreadable: {e}"))?;
    if authority.is_empty() { return Err("installed authority is empty".into()); }
    // additionally compare requested capabilities against approved authority
    Ok(())
}

match kernel.load_capsule(&dir, &principal, &manifest) {
    Ok(bound) => /* proceed */,
    Err(e) if e.to_string().contains("exceeds or cannot prove its installed authority") => {
        // fallback: install into the durable registry, then retry
        // astrid install ./my-capsule
        let bound = kernel.load_capsule(&dir, &principal, &manifest)?;
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: load_capsule or prepare_runtime_replacement is invoked for a capsule that (a) is not present in the durable registry, (b) is not inside the explicit workspace state dir (otherwise the earlier 'outside the explicit workspace portal' bail fires first), and (c) fails verify_installed_authority_for_runtime — e.g. the manifest requests capabilities beyond the installed authority.json, or the installed authority cannot be read/verified in the local materialization.

Common situations: Developers pointing a capsule at a manually copied or hand-edited directory instead of installing it through the registry; editing Capsule.toml to add capabilities that were never approved; moving a capsule dir outside the workspace portal; running with principal_store disabled so no durable authority exists; stale/missing authority.json next to the runtime.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

• manifest exceeds its installed capability approval: {details
• installed WASM executable differs from its authority receipt
• capsule '{}' is {}; explicit local approval is required
• durable capsule {id} has unsafe WIT metadata path {relative}
• durable capsule {id} manifest exceeds its authority receipt

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