legacy capsule authority root contains a non-regular entry:

Error message

legacy capsule authority root contains a non-regular entry: {}

What it means

active_receipt_files uses fs::symlink_metadata on each entry of the legacy authority root and requires every entry to be a regular file. If any entry is a symlink, directory, or other special file, the library throws this error to avoid reading receipt data through redirected or non-file objects.

Source

Thrown at crates/astrid-capsule-install/src/authority/leftover.rs:255

    }
    astrid_core::platform_fs::verify_no_redirects(&directory).with_context(|| {
        format!(
            "verify legacy capsule authority root {}",
            directory.display()
        )
    })?;
    let mut paths = Vec::new();
    let mut entries = fs::read_dir(&directory)
        .with_context(|| format!("read legacy capsule authority root {}", directory.display()))?
        .collect::<Result<Vec<_>, _>>()
        .with_context(|| format!("read legacy capsule authority root {}", directory.display()))?;
    entries.sort_by_key(fs::DirEntry::file_name);
    for entry in entries {
        let path = entry.path();
        let metadata = fs::symlink_metadata(&path)
            .with_context(|| format!("inspect leftover capsule authority {}", path.display()))?;
        if metadata.file_type().is_symlink() || !metadata.is_file() {
            bail!(
                "legacy capsule authority root contains a non-regular entry: {}",
                path.display()
            );
        }
        if path
            .extension()
            .is_some_and(|extension| extension.eq_ignore_ascii_case("json"))
        {
            paths.push(path);
        }
    }
    Ok(paths)
}

fn unique_quarantine_path(root: &Path, file_name: &std::ffi::OsStr) -> anyhow::Result<PathBuf> {
    let encoded = encoded_file_name(file_name);
    for index in 0_u32..1024 {
        let candidate = if index == 0 {

View on GitHub (pinned to affd8760f4)

Solutions

Move any subdirectories out of the authority root (e.g. mv backup/ ~/astrid-backup/) so only regular receipt files remain
Replace symlinked receipt files with real copies (rm symlink; cp target into place)
Exclude ~/.astrid/authority from symlink-based dotfile management
List entries with find ~/.astrid/authority ! -type f to locate the offending entry

Example fix

// before
~/.astrid/authority/old/ (subdirectory present)
// after
$ mv ~/.astrid/authority/old ~/astrid-archive/old
$ astrid migrate  # scan succeeds

Defensive patterns

Strategy: validation

Validate before calling

for entry in std::fs::read_dir(authority_root)? {
    let md = entry?.metadata()?;
    if !md.is_file() {
        anyhow::bail!("non-regular entry in authority root");
    }
}

Type guard

fn all_entries_regular(dir: &Path) -> bool {
    std::fs::read_dir(dir).map(|rd| rd.filter_map(Result::ok)
        .all(|e| std::fs::symlink_metadata(e.path()).map(|m| m.is_file()).unwrap_or(false))).unwrap_or(false)
}

Prevention

Keep the authority directory flat — no subdirectories or special files
Never symlink individual receipts; copy real files instead
Periodically run: find <authority-root> ! -type f -print as a hygiene check

When it happens

Trigger: Calling unique_relocated_receipt → active_receipt_files when any entry under the authority root (leftover.rs:255) fails the is_file/not-symlink check — e.g. a subdirectory was created inside the authority directory, or a receipt was replaced by a symlink.

Common situations: User manually creating a subfolder (backup/, old/) inside the authority directory; dotfile manager symlinking individual receipts; a named pipe or socket accidentally placed there.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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