astrid-runtime/astrid · error

non-workspace capsule installation requires the authoritativ

Error message

non-workspace capsule installation requires the authoritative RuntimePrincipalStore; route the request through KernelRequest::InstallCapsule

What it means

Non-workspace capsule installs must persist into the authoritative RuntimePrincipalStore. install_from_local_path_internal rejects any request where options.workspace is false and no storage backend was supplied, because without a store the installation would not be durable or visible to the kernel. The message tells the integrator to route the operation through KernelRequest::InstallCapsule instead of calling this low-level entry point directly.

Source

Thrown at crates/astrid-capsule-install/src/local.rs:549

            id: expected,
            version: expected_version,
        }),
        Some(authority),
    )
}

#[allow(clippy::needless_pass_by_value, clippy::too_many_lines)]
pub(crate) fn install_from_local_path_internal(
    source_dir: &Path,
    home: &AstridHome,
    options: InstallOptions,
    target_principal: &PrincipalId,
    workspace: InstallWorkspace<'_>,
    expected: Option<ExpectedCapsuleIdentity<'_>>,
    installed_authority: Option<InstalledAuthority>,
) -> anyhow::Result<InstallOutput> {
    if !options.workspace && options.storage.is_none() {
        bail!(
            "non-workspace capsule installation requires the authoritative \
             RuntimePrincipalStore; route the request through KernelRequest::InstallCapsule"
        );
    }
    let checked_workspace = if options.workspace {
        let root = workspace
            .root
            .context("workspace install requires a workspace root")?;
        Some(
            workspace
                .layout
                .resolve(root)
                .context("selected workspace state path is unsafe")?,
        )
    } else {
        None
    };
    let manifest_path = source_dir.join("Capsule.toml");

View on GitHub (pinned to affd8760f4)

Solutions

1. Set options.workspace = true and supply a workspace, or
2. Provide options.storage with a RuntimePrincipalStore handle for non-workspace installs
3. Best: emit a KernelRequest::InstallCapsule through the kernel so the authoritative store is used automatically
4. If this is a script/test, switch to the kernel-level install path rather than the internal API

Example fix

// before
install_from_local_path_internal(&src, &principal, &options /* workspace:false, storage:None */, ...)?;
// after
let options = InstallOptions { workspace: false, storage: Some(runtime_principal_store.clone()), ..options };
// or: kernel.submit(KernelRequest::InstallCapsule { source, principal, .. })

fn install_options_valid(opts: &InstallOptions) -> bool {
    opts.workspace || opts.storage.is_some()
}

if !options.workspace && options.storage.is_none() {
    kernel.submit(KernelRequest::InstallCapsule { /* ... */ })?;
} else {
    install_from_local_path_internal(...)?;
}

When it happens

Trigger: Calling install_from_local_path_internal (or any of its five public wrappers: unpack_and_install_internal, install_from_local_path_for_principal_in_workspace, install_from_local_path_checked/authorized/checked_authorized_for_principal_in_workspace) with options.workspace = false and options.storage = None.

Common situations: Custom tooling invoking the low-level install API directly instead of going through the kernel request channel; refactored code that dropped the storage option; tests or scripts that previously relied on ephemeral installs.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• capsule identity mismatch: expected '{expected}', manifest d
• capsule version mismatch for '{expected}': expected '{expect
• No Capsule.toml found in {}
• capsule identity mismatch: expected '{}', manifest declares
• capsule version mismatch for '{id}': expected '{expected_ver

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