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

AOS capsule directory contains a non-UTF-8 entry

Error message

AOS capsule directory contains a non-UTF-8 entry

What it means

Thrown by validate_capsule_dir when a filename inside the capsule directory is not valid UTF-8. Since capsule names are embedded into a TOML manifest and compared as Rust Strings, the library cannot represent non-UTF-8 names and rejects the directory.

Solutions

1. Rename the offending file to a valid UTF-8 name (e.g. `convmv -f latin1 -t utf8 -r --notest <dir>`)
2. Delete files with non-UTF-8 names and re-install capsules via install_capsule_fixtures
3. Ensure the tooling that creates capsule files runs under a UTF-8 locale

fn all_names_utf8(path: &std::path::Path) -> bool {
    std::fs::read_dir(path).map(|rd| {
        rd.filter_map(|e| e.ok()).all(|e| e.file_name().into_string().is_ok())
    }).unwrap_or(false)
}

match bootstrap::capsule_dir_with(&home) {
    Err(e) if e.to_string().contains("non-UTF-8 entry") => {
        eprintln!("Rename files with non-UTF-8 names in the capsule directory");
    }
    Err(e) => return Err(e),
    Ok(dir) => dir,
}

When it happens

Trigger: A file in the capsule directory has a name with invalid UTF-8 bytes (e.g. created on a filesystem with non-UTF-8 encoding or via raw bytes); entry.file_name().into_string() fails during capsule_dir_with validation.

Common situations: Files created by non-UTF-8 locale tooling; filenames with legacy encodings (Latin-1, GBK); corrupted downloads producing odd filenames.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• capsule asset is not UTF-8
• AOS capsule directory is unavailable at
• AOS capsule directory must be a real directory
• AOS capsule directory contains a non-regular entry
• AOS capsule set differs from Community Edition; expected

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

Appendix: source

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

            ),
        ));
    }
    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();
    if actual != expected {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            format!(
                "AOS capsule set differs from Community Edition; expected {}, found {}",
                expected.len(),
                actual.len()
            ),
        ));

View on GitHub (pinned to f6f22024fb)