astrid-runtime/astrid · error

runtime projection contains a special entry

Error message

runtime projection contains a special entry: {}

What it means

preflight_projection_entry only permits regular files and directories in the runtime projection tree; anything else (sockets, fifos, devices) triggers InvalidData naming the path. The preflight exists so retirement removes only well-understood content.

Solutions

1. Stop the process owning the special file and remove it, then retry retirement.
2. List offenders with: find <projection-root> ! -type f ! -type d and clean each.
3. Exclude such outputs from the projection directory (configure the producer to place sockets elsewhere).

Example fix

// before
projection/run.sock = unix socket
// after
kill <owner-pid>; rm projection/run.sock

fn assert_no_special(root: &Path) -> io::Result<()> {
    for e in walkdir_like(root) {
        let m = std::fs::symlink_metadata(&e)?;
        if !m.is_file() && !m.is_dir() {
            return Err(io::Error::new(io::ErrorKind::InvalidData, format!("special: {}", e.display())));
        }
    }
    Ok(())
}

fn is_plain_entry(p: &Path) -> bool {
    std::fs::symlink_metadata(p).map(|m| m.is_file() || m.is_dir()).unwrap_or(false)
}

match retire_projection_root(&path) {
    Err(e) if e.to_string().contains("special entry") => { /* stop owner process, delete entry, retry */ }
    other => other?,
}

When it happens

Trigger: A special file exists in the projection root (at any depth) when retire_projection_root performs its preflight pass.

Common situations: A long-running process left a unix socket in the projection dir; dev nodes or fifos appeared via mounted volumes or debug tooling.

Related errors

• legacy state source contains a special file
• audit fixture
• capsule ' ' has no source directory
• capsule path escaped source root
• capsule path is not valid UTF-8

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/1d60e8724c0a145a. Report an issue: GitHub.

Appendix: source

Thrown at crates/astrid-core/src/dirs_projection_retirement.rs:57

}

fn preflight_projection_entry(path: &Path) -> io::Result<()> {
    let metadata = std::fs::symlink_metadata(path)?;
    if metadata.file_type().is_symlink() {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            format!("runtime projection is redirected: {}", path.display()),
        ));
    }
    if metadata.is_dir() {
        for entry in std::fs::read_dir(path)? {
            let child = entry?.path();
            preflight_projection_entry(&child)?;
        }
        return Ok(());
    }
    if !metadata.is_file() {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            format!(
                "runtime projection contains a special entry: {}",
                path.display()
            ),
        ));
    }
    Ok(())
}

View on GitHub (pinned to affd8760f4)