{"record":{"id":"9a4464a85d11bd35","repo":"unicity-aos/aos-ce","slug":"imported-principal-home-contains-a-non-utf-8-name","errorCode":null,"errorMessage":"imported principal home contains a non-UTF-8 name","messagePattern":"imported principal home contains a non-UTF-8 name","errorType":"validation","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"crates/unicity-aos-bootstrap/src/migration.rs","lineNumber":349,"sourceCode":"fn archive_inactive_activation_state(staging: &Path, entries: &mut [Entry]) -> io::Result<()> {\n    let ce_capsules = unicity_ce_capsule_names()?;\n    archive_non_default_profiles(staging, entries)?;\n\n    let homes = staging.join(\"home\");\n    let homes_metadata = match fs::symlink_metadata(&homes) {\n        Ok(metadata) => metadata,\n        Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(()),\n        Err(error) => return Err(error),\n    };\n    if homes_metadata.file_type().is_symlink() || !homes_metadata.is_dir() {\n        return invalid(\"imported principal homes must be a real directory\");\n    }\n\n    let mut principal_names = Vec::new();\n    for principal in fs::read_dir(&homes)? {\n        let principal = principal?;\n        let principal_name = principal.file_name().into_string().map_err(|_| {\n            io::Error::new(\n                io::ErrorKind::InvalidInput,\n                \"imported principal home contains a non-UTF-8 name\",\n            )\n        })?;\n        let metadata = fs::symlink_metadata(principal.path())?;\n        if metadata.file_type().is_symlink() {\n            return invalid(\"imported principal home must be a real directory\");\n        }\n        if metadata.is_file() {\n            continue;\n        }\n        if !metadata.is_dir() {\n            return invalid(\"imported principal home contains a special file\");\n        }\n        principal_names.push(principal_name);\n    }\n\n    for principal_name in principal_names {","sourceCodeStart":331,"sourceCodeEnd":367,"githubUrl":"https://github.com/unicity-aos/aos-ce/blob/f6f22024fb1e8d122f28a1b4a9f75aee448ae839/crates/unicity-aos-bootstrap/src/migration.rs#L331-L367","documentation":"`archive_inactive_activation_state` iterates the imported `homes` directory and converts each principal entry name with `OsStr::into_string()`. If a principal home directory name is not valid UTF-8, the archive step cannot record it in the manifest, so an `InvalidInput` error is raised.","triggerScenarios":"Running `migrate_runtime` on a source whose `homes/` directory contains an entry whose name has non-UTF-8 bytes (e.g. legacy-encoded usernames created by non-UTF-8 locale tooling).","commonSituations":"Systems where user accounts were created with Samba/legacy tools using Latin-1 names; imported archives (tar/zip) that decoded filenames incorrectly; manually created directories with raw-byte names.","solutions":["Find the offending entry with a byte-aware listing (e.g. `ls homes/ | LC_ALL=C grep -vP '^[\\x00-\\x7F\\x80-\\xFF]*$'` or `find homes -maxdepth 1 \\! -regex '.*[[:print:]]*'`) and rename it to UTF-8.","Re-create the affected principal's home with a UTF-8 name and move its contents across before migrating.","Re-export the source state from a system using a UTF-8 locale so filenames are encoded as UTF-8.","If the entry is garbage, delete it — inactive activation state that cannot be named cannot be preserved."],"exampleFix":"// shell: rename non-UTF-8 principal home before migration\n// before\nmv $'homes/caf\\xe9' homes/cafe\n\n// after: homes/ contains only UTF-8 names, migration succeeds","handlingStrategy":"validation","validationCode":"for entry in fs::read_dir(source.join(\"homes\"))? {\n    let entry = entry?;\n    if entry.file_name().to_str().is_none() {\n        return Err(anyhow!(\"non-UTF-8 principal home: {:?}\", entry.file_name()));\n    }\n}","typeGuard":"fn is_utf8_name(e: &std::fs::DirEntry) -> bool { e.file_name().to_str().is_some() }","tryCatchPattern":"if err.to_string().contains(\"non-UTF-8 name\") {\n    eprintln!(\"rename the offending principal home to UTF-8 and retry\");\n}","preventionTips":["Create user/principal homes under a UTF-8 locale only.","Extract archives with UTF-8 filename decoding.","Pre-scan the homes directory for non-UTF-8 names before migrating."],"tags":["encoding","migration","filesystem","rust"],"backgroundTag":"invalid-identifier-format","analyzedSha":"f6f22024fb1e8d122f28a1b4a9f75aee448ae839","analyzedAt":"2026-09-13T03:04:44.565Z","contentChangedAt":"2026-09-13T03:04:44.565Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}