unicity-aos/aos-ce · error · io::Error

AOS capsule directory contains a non-regular entry

Error message

AOS capsule directory contains a non-regular entry: {}

What it means

Thrown by validate_capsule_dir when an entry inside the capsule directory is a symlink or not a regular file. The library requires every entry to be a plain file so the capsule set is tamper-evident and portable; nested directories, links, devices, or sockets are rejected.

Solutions

1. Remove or replace any non-regular entry inside the capsule directory with a regular file copy
2. Ensure only the expected .capsule files (plain files) are present
3. Clean and regenerate the directory via install_capsule_fixtures

Example fix

// before
ln -s /opt/capsules/auth.capsule ~/.aos/capsules/auth.capsule
// after
cp /opt/capsules/auth.capsule ~/.aos/capsules/auth.capsule

fn dir_has_only_regular_files(path: &std::path::Path) -> bool {
    std::fs::read_dir(path).map(|rd| rd.filter_map(|e| e.ok()).all(|e| {
        std::fs::symlink_metadata(e.path())
            .map(|md| !md.file_type().is_symlink() && md.is_file())
            .unwrap_or(false)
    })).unwrap_or(false)
}

match bootstrap::capsule_dir_with(&home) {
    Err(e) if e.to_string().contains("non-regular entry") => {
        eprintln!("Remove or flatten non-file entries inside the capsule directory: {e}");
    }
    Err(e) => return Err(e),
    Ok(dir) => dir,
}

When it happens

Trigger: Placing subdirectories, symlinks, sockets, or device nodes inside the capsule directory before calling capsule_dir_with; leaving editor/VCS artifacts (e.g. symlinked files) inside the directory.

Common situations: Users pre-populating the directory with unpacked capsule trees; symlinking capsule files into the directory from elsewhere; leftover temporary files from interrupted runs.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• AOS capsule directory must be a real directory
• product manifest path must be a regular file
• temporary product manifest path must be a regular file
• AOS managed path must be a real directory
• AOS capsule directory is unavailable at

AI-assisted analysis of unicity-aos/aos-ce@f6f22024fb (2026-09-13). Data as JSON: /api/errors/ed0ae6095691c4a0. Report an issue: GitHub.

Appendix: source

Thrown at crates/unicity-aos-bootstrap/src/lib.rs:739

            ),
        )
    })?;
    if metadata.file_type().is_symlink() || !metadata.is_dir() {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            format!(
                "AOS capsule directory must be a real directory: {}",
                path.display()
            ),
        ));
    }
    let canonical = path.canonicalize()?;
    let mut actual = Vec::new();
    for entry in fs::read_dir(&canonical)? {
        let entry = entry?;
        let metadata = fs::symlink_metadata(entry.path())?;
        if metadata.file_type().is_symlink() || !metadata.is_file() {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                format!(
                    "AOS capsule directory contains a non-regular entry: {}",
                    entry.path().display()
                ),
            ));
        }
        let name = entry.file_name().into_string().map_err(|_| {
            io::Error::new(
                io::ErrorKind::InvalidInput,
                "AOS capsule directory contains a non-UTF-8 entry",
            )
        })?;
        actual.push(name);
    }
    actual.sort();
    let mut expected = expected.to_vec();
    expected.sort();

View on GitHub (pinned to f6f22024fb)