{"record":{"id":"89b9af35d827f3cb","repo":"astrid-runtime/astrid","slug":"capsule-projection-contains-a-special-file","errorCode":null,"errorMessage":"capsule projection contains a special file: {}","messagePattern":"capsule projection contains a special file: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-kernel/src/lib.rs","lineNumber":1651,"sourceCode":"                    anyhow::anyhow!(\"capsule projection path is not UTF-8: {}\", path.display())\n                })?;\n                let metadata = std::fs::symlink_metadata(&path).map_err(|error| {\n                    anyhow::anyhow!(\"inspect capsule projection {}: {error}\", path.display())\n                })?;\n                let file_type = metadata.file_type();\n                if file_type.is_symlink() {\n                    anyhow::bail!(\n                        \"capsule projection contains a symbolic link: {}\",\n                        path.display()\n                    );\n                }\n                if file_type.is_dir() {\n                    inventory.directories.insert(relative_text.to_owned());\n                    walk(root, &path, inventory)?;\n                } else if file_type.is_file() {\n                    inventory.files.insert(relative_text.to_owned());\n                } else {\n                    anyhow::bail!(\n                        \"capsule projection contains a special file: {}\",\n                        path.display()\n                    );\n                }\n            }\n            Ok(())\n        }\n\n        let mut inventory = ProjectionInventory::default();\n        walk(root, root, &mut inventory)?;\n        Ok(inventory)\n    }\n\n    #[cfg(not(all(target_arch = \"wasm32\", target_os = \"unknown\")))]\n    fn read_projection_file_nofollow(path: &Path) -> anyhow::Result<Vec<u8>> {\n        use std::io::Read as _;\n\n        let metadata = std::fs::symlink_metadata(path).map_err(|error| {","sourceCodeStart":1633,"sourceCodeEnd":1669,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-kernel/src/lib.rs#L1633-L1669","documentation":"This error means the projection inventory walk encountered a file that is neither a regular file nor a directory (e.g. a FIFO, device node, socket, or other special file). The kernel throws it because capsule projections must consist solely of ordinary files/directories; special files cannot be safely inventoried or projected and may hang reads or expose host devices.","triggerScenarios":"The recursive inventory walk (walk over the materialized capsule directory) hits a directory entry whose symlink_metadata file type is neither file nor dir — e.g. a named pipe or unix socket created inside the capsule directory by a build step or a process writing into the projection.","commonSituations":"A build tool creating FIFOs/sockets in the output directory before packaging; a dev server writing a .sock file into the capsule dir; packaging /dev-like trees; an archive that contained device nodes and was extracted with privileges.","solutions":["Remove the special file shown in the error from the capsule directory and re-inventory","Fix the build/run step that creates FIFOs/sockets in the capsule output (write them to a temp dir instead)","Repackage the capsule from a clean build output containing only regular files","Investigate any process still writing into the materialized capsule directory and stop it before activation"],"exampleFix":"# before: build leaves a socket in the output\nmy-server --socket build/capsule.sock\n\n# after: keep runtime artifacts out of the capsule output\nmy-server --socket /tmp/app.sock","handlingStrategy":"validation","validationCode":"let ft = std::fs::symlink_metadata(p)?.file_type();\nif !(ft.is_file() || ft.is_dir()) {\n    return Err(format!(\"special file in capsule output: {}\", p.display()));\n}","typeGuard":null,"tryCatchPattern":"match result {\n    Err(e) if e.to_string().contains(\"special file\") => {\n        // remove the FIFO/socket/device node and rebuild\n    }\n    other => other?,\n}","preventionTips":["Keep runtime artifacts (sockets, FIFOs) out of capsule output dirs","Clean build output before packaging","Prune non-regular files in the packaging step","Avoid packaging device or proc-like trees"],"tags":["filesystem","validation","capsule","special-file"],"backgroundTag":"unsupported-operation","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"}