{"record":{"id":"f7756f7f89defbb8","repo":"unicity-aos/aos-ce","slug":"imported-capsule-installation-contains-a-non-utf-8-name","errorCode":null,"errorMessage":"imported capsule installation contains a non-UTF-8 name","messagePattern":"imported capsule installation contains a non-UTF-8 name","errorType":"validation","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"crates/unicity-aos-bootstrap/src/migration.rs","lineNumber":390,"sourceCode":"        let capsules_metadata = match fs::symlink_metadata(&capsules) {\n            Ok(metadata) => metadata,\n            Err(error) if error.kind() == io::ErrorKind::NotFound => continue,\n            Err(error) => return Err(error),\n        };\n        if capsules_metadata.file_type().is_symlink() || !capsules_metadata.is_dir() {\n            return invalid(\"imported capsule installation root must be a real directory\");\n        }\n\n        if principal_name != \"default\" {\n            archive_path(staging, &relative, entries)?;\n            continue;\n        }\n\n        let mut inactive_capsules = Vec::new();\n        for capsule in fs::read_dir(&capsules)? {\n            let capsule = capsule?;\n            let name = capsule.file_name().into_string().map_err(|_| {\n                io::Error::new(\n                    io::ErrorKind::InvalidInput,\n                    \"imported capsule installation contains a non-UTF-8 name\",\n                )\n            })?;\n            let metadata = fs::symlink_metadata(capsule.path())?;\n            if metadata.file_type().is_symlink() {\n                return invalid(\"imported capsule installation must not be a symlink\");\n            }\n            if !metadata.is_dir() && !metadata.is_file() {\n                return invalid(\"imported capsule installation contains a special file\");\n            }\n            let active_ce_capsule = metadata.is_dir()\n                && imported_capsule_package_name(&capsule.path()).as_deref() == Some(&name)\n                && ce_capsules.contains(&name);\n            if !active_ce_capsule {\n                inactive_capsules.push(name);\n            }\n        }","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/unicity-aos/aos-ce/blob/f6f22024fb1e8d122f28a1b4a9f75aee448ae839/crates/unicity-aos-bootstrap/src/migration.rs#L372-L408","documentation":"Inside `archive_inactive_activation_state`, the inactive-capsules scan converts each capsule directory entry name with `into_string()`. If a capsule installation name under the imported state is not valid UTF-8, it cannot be represented in the migration manifest, so an `InvalidInput` error is raised.","triggerScenarios":"Running `migrate_runtime` where the imported inactive capsule installation directory contains an entry whose filename has non-UTF-8 bytes (e.g. capsule dirs created by scripts using legacy encodings).","commonSituations":"Capsule directories extracted from zip archives with non-UTF-8 filename flags; directories produced on a system with a non-UTF-8 locale; manual file operations using raw byte names.","solutions":["List the inactive capsule directory byte-wise (`LC_ALL=C ls`) to identify the non-UTF-8 entry and rename it with a valid UTF-8 name.","Reinstall or re-extract the affected capsule so its directory name is UTF-8, then retry the migration.","Remove the offending capsule entry if it is no longer needed (it is inactive state and cannot be archived otherwise).","Normalize the source state on a UTF-8 locale system (e.g. `convmv --notest -f latin1 -t utf8 -r <capsules-dir>`) before migrating."],"exampleFix":"// shell: fix non-UTF-8 capsule directory name before migration\n// before\nconvmv -f latin1 -t utf8 -r --notest run/capsules/\n\n// after: all capsule names are valid UTF-8, migration proceeds","handlingStrategy":"validation","validationCode":"for entry in fs::read_dir(capsules_dir)? {\n    let entry = entry?;\n    if entry.file_name().to_str().is_none() {\n        return Err(anyhow!(\"non-UTF-8 capsule name: {:?}\", 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 or remove the offending capsule directory and retry\");\n}","preventionTips":["Install capsules only via tools that produce UTF-8 directory names.","Normalize legacy-encoded capsule dirs with convmv before migrating.","Pre-scan inactive capsule directories for non-UTF-8 names."],"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"}