{"record":{"id":"16e7872b5726a46f","repo":"unicity-aos/aos-ce","slug":"failed-to-validate-ephemeral-state-exclusion-error","errorCode":null,"errorMessage":"failed to validate ephemeral state exclusion: {error}","messagePattern":"failed to validate ephemeral state exclusion: (.+?)","errorType":"validation","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"crates/unicity-aos-bootstrap/src/migration.rs","lineNumber":278,"sourceCode":"        let mut entries = Vec::new();\n        copy_etc_state(&source, &staging, &mut entries)?;\n        for name in PERSISTENT_TOP_LEVEL {\n            copy_if_present(\n                &source.join(name),\n                &staging.join(name),\n                Path::new(name),\n                &mut entries,\n            )?;\n        }\n        copy_wasm_blobs(&source.join(\"bin\"), &staging.join(\"bin\"), &mut entries)?;\n        archive_inactive_activation_state(&staging, &mut entries).map_err(|error| {\n            io::Error::new(\n                error.kind(),\n                format!(\"failed to preserve imported activation state: {error}\"),\n            )\n        })?;\n        ensure_no_ephemeral_data(&staging).map_err(|error| {\n            io::Error::new(\n                error.kind(),\n                format!(\"failed to validate ephemeral state exclusion: {error}\"),\n            )\n        })?;\n        entries.sort_by(|left, right| left.path.cmp(&right.path));\n        let legacy_distros = legacy_distros(&staging).map_err(|error| {\n            io::Error::new(\n                error.kind(),\n                format!(\"failed to inspect imported distro locks: {error}\"),\n            )\n        })?;\n        let receipt = Receipt {\n            migration_version: MIGRATION_VERSION,\n            schema_version: RECEIPT_SCHEMA_VERSION,\n            source: source.clone(),\n            entries,\n            legacy_distros,\n        };","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/unicity-aos/aos-ce/blob/f6f22024fb1e8d122f28a1b4a9f75aee448ae839/crates/unicity-aos-bootstrap/src/migration.rs#L260-L296","documentation":"`migrate_runtime` calls `ensure_no_ephemeral_data` on the staged runtime and wraps failures as \"failed to validate ephemeral state exclusion\". This check guarantees no ephemeral data (caches, sockets, tmp state) was copied into the staging tree; a failure here means the validation walk itself errored, so the migration aborts rather than importing potentially dirty state.","triggerScenarios":"An I/O error raised by `ensure_no_ephemeral_data` while scanning the staged tree during `migrate_runtime` — e.g. unreadable staged directories, symlink loops, or vanished files mid-scan.","commonSituations":"Staging on a filesystem that errors on traversal (failing disk, network mount flaps), or an import source containing exotic entries (broken symlinks, permission-denied subdirs) that break the ephemeral-state scan.","solutions":["Inspect the wrapped inner error to identify which staged path failed, then fix that entry (permissions, broken symlink) and retry.","Re-run the migration to rebuild the staging tree if the failure was transient (e.g. network filesystem hiccup).","Exclude ephemeral/cache directories from the source before import so the staged tree is clean and scannable.","Stage on a reliable local filesystem rather than a network mount to avoid traversal errors."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"scan_tree(&staging, |p| fs::metadata(p).map(|_| ()).map_err(|e| e.to_string()))?;","typeGuard":null,"tryCatchPattern":"if let Some(io_err) = err.downcast_ref::<io::Error>() {\n    if let Some(inner) = io_err.to_string().strip_prefix(\"failed to validate ephemeral state exclusion: \") {\n        eprintln!(\"ephemeral scan failed at: {inner}\");\n    }\n}","preventionTips":["Stage migrations on a healthy local filesystem, not network mounts.","Exclude ephemeral/cache directories from the import source beforehand.","Retry the migration once on transient filesystem errors."],"tags":["migration","filesystem","validation","rust"],"backgroundTag":"file-read-failed","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"}