{"record":{"id":"273d110772fd7306","repo":"astrid-runtime/astrid","slug":"legacy-principal-home-source-path-principal-dir","errorCode":null,"errorMessage":"legacy principal-home source {path}: principal directory name is not UTF-8","messagePattern":"legacy principal-home source (.+?): principal directory name is not UTF-8","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-kernel/src/principal_home_migration/mod.rs","lineNumber":96,"sourceCode":"    }\n    astrid_core::platform_fs::ensure_private_directory_tree(&source_root)?;\n    astrid_core::platform_fs::verify_no_redirects(&source_root)?;\n    astrid_core::platform_fs::ensure_private_directory(&home.migrations_dir())?;\n\n    let entries = fs::read_dir(&source_root).map_err(|error| {\n        io::Error::new(\n            error.kind(),\n            format!(\"scan {}: {error}\", source_root.display()),\n        )\n    })?;\n    for entry in entries {\n        let entry = entry?;\n        let alias_name = entry.file_name();\n        let alias_text = alias_name.to_str().ok_or_else(|| {\n            invalid_source(&entry.path(), \"principal directory name is not UTF-8\")\n        })?;\n        let alias = PrincipalId::new(alias_text.to_owned()).map_err(|error| {\n            io::Error::new(\n                io::ErrorKind::InvalidData,\n                format!(\"legacy principal directory {alias_text:?} is invalid: {error}\"),\n            )\n        })?;\n        // A migration receipt is immutable provenance and takes precedence\n        // over the mutable alias directory. If an alias was deleted and then\n        // reused, never stream the surviving old source into the replacement\n        // UID; fail closed instead.\n        let receipt_uid = receipt_uid_for_alias(home, &alias)?;\n        let live_uid = principals.uid_for(&alias).ok();\n        let uid = match (receipt_uid, live_uid) {\n            (Some(receipt), Some(live)) if receipt != live => {\n                return Err(conflict_path(\n                    &entry.path(),\n                    \"migration receipt UID differs from the live alias binding\",\n                ));\n            },\n            (Some(receipt), _) => receipt,","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-kernel/src/principal_home_migration/mod.rs#L78-L114","documentation":"Raised when a directory entry in the legacy principal-home source root has a filename that is not valid UTF-8. Principal identifiers are text, so a non-UTF-8 directory name cannot be interpreted as a principal alias. Reported via invalid_source with ErrorKind::InvalidData.","triggerScenarios":"Calling migrate_legacy_principal_homes when an entry under the source root has a non-UTF-8 name, typically from files created with raw bytes (e.g. on Linux filesystems that allow arbitrary byte names).","commonSituations":"Directories created by non-Rust tools with locale-mismatched encoding, accidentally extracted archives with binary-named entries, NFS mounts with different encodings.","solutions":["Rename the offending directory to a valid UTF-8 principal name","Remove the non-UTF-8 entry if it is junk","Find it with: find <source_root> -maxdepth 1 | grep -vP '[\\x00-\\x7F]*'","Re-run migration after cleaning the directory listing"],"exampleFix":"// before: rename non-UTF-8 entry manually\nmv $'home/bad\\xffname' home/badname\n// after: migration proceeds\nmigrate_legacy_principal_homes(&home, &store)?;","handlingStrategy":"validation","validationCode":"fn alias_names_ok(root: &Path) -> bool {\n    std::fs::read_dir(root).map(|rd| rd.filter_map(Result::ok).all(|e| e.file_name().to_str().is_some())).unwrap_or(false)\n}","typeGuard":"fn is_utf8_entry(e: &std::fs::DirEntry) -> bool { e.file_name().to_str().is_some() }","tryCatchPattern":"match result {\n    Err(e) if e.kind() == io::ErrorKind::InvalidData && e.to_string().contains(\"not UTF-8\") => {\n        rename_non_utf8_entries(&source_root)?;\n        retry()\n    }\n    other => other,\n}","preventionTips":["Scan the legacy tree for non-UTF-8 names before migrating (find | grep -P '[^\\x00-\\x7F]')","Create files with UTF-8-safe tooling and locales","Delete junk entries with binary names before migration"],"tags":["filesystem","encoding","utf-8","migration"],"backgroundTag":"invalid-identifier-format","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}