capsules are installed, but granting capsule access failed:

Error message

capsules are installed, but granting capsule access failed: {e}
  Finish manually:
  {}

What it means

This error is raised in grant_installed_capsules (via apply_or_hint_grants) when capsules were successfully installed for an agent, but the follow-up step of granting that agent modify access to them failed. Because the automated grant failed (e.g. the OS ACL/chmod operation returned an error), the CLI aborts and prints the exact manual command (agent_modify_grant_command) the user can run to finish the setup by hand.

Source

Thrown at crates/astrid-cli/src/commands/init_grant.rs:531

                "{}",
                Theme::success(&format!(
                    "Granted capsule access to '{target}': [{}]",
                    outcome.capsules.join(", ")
                ))
            );
            Ok(())
        },
        Ok(_) => {
            eprintln!(
                "{}",
                Theme::info(&format!(
                    "'{target}' already had access to every installed capsule (no change)."
                ))
            );
            Ok(())
        },
        Err(e) => {
            bail!(
                "capsules are installed, but granting capsule access failed: {e}\n  \
                 Finish manually:\n  {}",
                agent_modify_grant_command(operator, target, installed)
            );
        },
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::commands::capsule::{install, meta};
    use crate::commands::init::LockedCapsule;

    #[test]
    fn explicit_grants_include_completed_batches_and_idempotent_resume() {
        let completed: Vec<_> = (0..22)
            .map(|i| LockedCapsule {

View on GitHub (pinned to affd8760f4)

Solutions

Run the manual command printed in the error message (agent_modify_grant_command output) to grant access yourself.
Check ownership/permissions of the capsule install directory and re-run init as a user with rights to modify ACLs.
Fix the underlying cause shown in `{e}` (e.g. missing ACL tool, read-only mount) and re-run `astrid init`.

Example fix

// before (automated grant fails, init aborts)
astrid init --agent codex
// error: granting capsule access failed ...

// after: run the suggested manual grant
chmod -R u+rwX,g+rx ~/.astrid/capsules  # or the agent_modify_grant_command printed

Defensive patterns

Strategy: try-catch

Validate before calling

// before init
test -w ~/.astrid/capsules && echo writable || echo "fix ownership/permissions first"
command -v setfacl >/dev/null && echo "acl tools present" || echo "install acl tools"

Try / catch

// shell
if ! astrid init --agent codex; then
  echo "automated grant failed; applying manual grant"
  eval "$(astrid agent grant-command codex installed-capsules)" # command printed in the error
fi

Prevention

Run init as a user that owns the capsule install directory.
Verify the target agent user exists and ACL tooling (setfacl) is installed.
Avoid read-only mounts for the capsule directory.

When it happens

Trigger: apply_or_hint_grants -> grant_installed_capsules runs after capsule installation; the internal grant operation returns Err(e) for the target agent, so the function bails with the underlying error plus the manual grant command.

Common situations: Running `astrid init` on a system where permission changes fail: read-only filesystem, lack of ownership of the capsule directory, restricted ACL tooling (missing setfacl/chmod rights), sandboxed CI environments, or the target agent user not existing.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

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