{"record":{"id":"76b63183c46f9f1b","repo":"astrid-runtime/astrid","slug":"capsule-source-contains-unsupported-special-file","errorCode":null,"errorMessage":"capsule source contains unsupported special file {}","messagePattern":"capsule source contains unsupported special file (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-capsule-install/src/storage.rs","lineNumber":829,"sourceCode":"                || relative.file_name().and_then(|name| name.to_str()) == Some(\"target\")\n            {\n                continue;\n            }\n            // Directory entries are included so empty directories survive\n            // archive round-trips; their descendants are sorted recursively.\n            entries.push((relative.clone(), metadata));\n            collect_entries(root, &name, entries)?;\n        } else if file_type.is_file() {\n            let name = relative.file_name().and_then(|name| name.to_str());\n            if matches!(\n                name,\n                Some(\"meta.json\" | \"authority.json\" | \".env\" | \".env.json\")\n            ) {\n                continue;\n            }\n            entries.push((relative, metadata));\n        } else {\n            bail!(\n                \"capsule source contains unsupported special file {}\",\n                relative.display()\n            );\n        }\n    }\n    Ok(())\n}\n\nfn read_dir_sorted(path: &Path) -> anyhow::Result<Vec<(PathBuf, Metadata)>> {\n    let mut children = Vec::new();\n    let entries: ReadDir = fs::read_dir(path)\n        .with_context(|| format!(\"read capsule source directory {}\", path.display()))?;\n    for entry in entries {\n        let entry = entry.with_context(|| format!(\"read child of {}\", path.display()))?;\n        let name = entry.path();\n        let metadata = fs::symlink_metadata(&name)\n            .with_context(|| format!(\"inspect capsule source entry {}\", name.display()))?;\n        children.push((name, metadata));","sourceCodeStart":811,"sourceCodeEnd":847,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-capsule-install/src/storage.rs#L811-L847","documentation":"Raised by collect_entries when a capsule source entry is neither a regular file, directory, nor an accepted symlink — i.e. an unsupported special file (FIFO, socket, device node). The library skips known metadata files but rejects any other non-regular entry to keep archives deterministic and portable.","triggerScenarios":"Building a canonical archive from a source directory containing a FIFO/socket/device file at any depth; the entry is not named meta.json, authority.json, .env, or .env.json and is not a dir/file/symlink.","commonSituations":"Runtime artifacts (sockets from a dev server, pipes from build tooling) left inside the capsule directory; odd entries produced by container mounts or FUSE filesystems; a bad restore that created device nodes.","solutions":["Delete or move the special file named in the message out of the capsule source directory.","Stop the process that created the socket/FIFO and clean the directory before archiving.","Archive from a clean checkout/build output containing only regular files and directories."],"exampleFix":"# before: dev-server socket inside capsule root\nmy-capsule/dev.sock\n\n# after\nrm my-capsule/dev.sock","handlingStrategy":"validation","validationCode":"fn only_regular_entries(dir: &Path) -> std::io::Result<bool> {\n    Ok(!walkdir(dir).any(|e| !e.file_type().is_file() && !e.file_type().is_dir()))\n}","typeGuard":"fn is_archive_safe(md: &std::fs::FileType) -> bool {\n    md.is_file() || md.is_dir()\n}","tryCatchPattern":"match publish(...) {\n    Err(e) if e.to_string().contains(\"unsupported special file\") => { remove_special_files(&dir)?; retry(); }\n    other => other?,\n}","preventionTips":["Run dev servers with sockets outside the capsule dir","Clean build/runtime artifacts before publishing","Publish from fresh CI checkouts rather than shared workspaces"],"tags":["special-file","archive-validation","capsule"],"backgroundTag":"unsupported-operation","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}