astrid-runtime/astrid · error

legacy capsule authority root is not a regular directory: {}

Error message

legacy capsule authority root is not a regular directory: {}

What it means

legacy_authority_receipt_status validates that the legacy authority root is a plain directory (symlink_metadata: not a symlink, is_dir) before listing receipt status. If the path is a symlink or non-directory, this error is thrown — the library will not report status through a redirected filesystem object.

Source

Thrown at crates/astrid-capsule-install/src/authority/status.rs:46

///
/// Returns an error when the receipt directory or one of its entries is
/// redirected, special, or unreadable.
pub fn legacy_authority_receipt_status(
    home: &AstridHome,
    workspace_targets: &[PathBuf],
) -> anyhow::Result<LegacyAuthorityReceiptStatus> {
    let directory = home.etc_dir().join(AUTHORITY_RECEIPT_DIR);
    let metadata = match std::fs::symlink_metadata(&directory) {
        Ok(metadata) => metadata,
        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
            return Ok(LegacyAuthorityReceiptStatus::default());
        },
        Err(error) => {
            return Err(error).with_context(|| format!("inspect {}", directory.display()));
        },
    };
    if metadata.file_type().is_symlink() || !metadata.is_dir() {
        bail!(
            "legacy capsule authority root is not a regular directory: {}",
            directory.display()
        );
    }
    astrid_core::platform_fs::verify_no_redirects(&directory).with_context(|| {
        format!(
            "verify legacy capsule authority root {}",
            directory.display()
        )
    })?;

    let permitted = workspace_targets
        .iter()
        .map(|target| authority_paths(home, target).map(|paths| paths.active))
        .collect::<anyhow::Result<BTreeSet<_>>>()?;
    let mut status = LegacyAuthorityReceiptStatus::default();
    let mut entries = std::fs::read_dir(&directory)
        .with_context(|| format!("read legacy capsule authority root {}", directory.display()))?

View on GitHub (pinned to affd8760f4)

Solutions

  1. Replace the symlink with a real directory (rm symlink; mkdir; copy contents back)
  2. Correct ASTRID_HOME/workspace configuration to point at a genuine directory
  3. Stop the dotfile manager from symlinking the authority directory and track its files directly
  4. Confirm the path with stat before re-running the status command

Example fix

// before
$ stat -c %F ~/.astrid/authority
symbolic link
// after
$ rm ~/.astrid/authority && mkdir ~/.astrid/authority
$ cp -aL /dotfiles/authority/. ~/.astrid/authority/
$ astrid authority status
Defensive patterns

Strategy: validation

Validate before calling

let root = authority_root_path();
let md = std::fs::symlink_metadata(&root)?;
if md.is_symlink() || !md.is_dir() {
    eprintln!("{} is not a real directory; fix before checking status", root.display());
    std::process::exit(1);
}

Type guard

fn authority_root_is_real_dir(p: &Path) -> bool {
    std::fs::symlink_metadata(p).map(|m| !m.is_symlink() && m.is_dir()).unwrap_or(false)
}

Prevention

When it happens

Trigger: Calling legacy_capsule_authority_status (or the test/CLI paths authority_status_blocks_unknown_but_preserves_workspace_portal_receipts) when the authority root at status.rs:46 is a symlink, a regular file, or another non-directory entry — usually because ~/.astrid/authority was symlinked by a dotfile manager or replaced by a file.

Common situations: chezmoi/stow symlinked .astrid; ASTRID_HOME misconfigured to a file path; an install script accidentally wrote a file at the authority path.

Related errors

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