astrid-runtime/astrid · error

{} is not a real directory: {}

Error message

{} is not a real directory: {}

What it means

This error is thrown while validating the ASTRID_RUN_DIR environment variable: the configured path exists (symlink_metadata succeeded) but its metadata says it is not a directory (e.g. it is a regular file, socket, or fifo). Astrid requires the run dir to be either nonexistent (it will be created) or a real, non-symlinked directory, so any other file type is rejected with io::ErrorKind::InvalidData before the daemon starts writing runtime state there.

Source

Thrown at crates/astrid-core/src/dirs_run_dir.rs:44

    if !path.is_absolute() {
        return Err(invalid("must be an absolute path"));
    }
    if path
        .components()
        .any(|component| matches!(component, Component::ParentDir | Component::CurDir))
    {
        return Err(invalid("must not contain '.' or '..' path components"));
    }

    match std::fs::symlink_metadata(&path) {
        Ok(metadata) if metadata.file_type().is_symlink() => {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!("{VARIABLE} is redirected: {}", path.display()),
            ));
        },
        Ok(metadata) if !metadata.is_dir() => {
            return Err(io::Error::new(
                io::ErrorKind::InvalidData,
                format!("{VARIABLE} is not a real directory: {}", path.display()),
            ));
        },
        Ok(_) => {},
        Err(error) if error.kind() == io::ErrorKind::NotFound => {},
        Err(error) => return Err(error),
    }
    crate::platform_fs::verify_no_redirects(&path)?;

    let physical_run = physical_path(&path)?;
    let physical_root = physical_path(home.root())?;
    if paths_are_related(&physical_run, &physical_root)
        || directories_are_aliases(&physical_run, &physical_root)
    {
        return Err(io::Error::new(
            io::ErrorKind::InvalidData,
            format!(

View on GitHub (pinned to affd8760f4)

Solutions

  1. Check the path with `ls -ld "$ASTRID_RUN_DIR"`; if it is a file, remove or rename it (`mv "$ASTRID_RUN_DIR" "$ASTRID_RUN_DIR.bak"`) so Astrid can create a directory there
  2. Point ASTRID_RUN_DIR at a path that is a real directory (e.g. /run/astrid or a tmpfs mount) instead of a file
  3. If the entry is a symlink, point ASTRID_RUN_DIR at the real target directory directly (symlinks are rejected separately)

Example fix

// before
export ASTRID_RUN_DIR=/var/run/astrid.pid   # a file
// after
rm /var/run/astrid.pid
export ASTRID_RUN_DIR=/var/run/astrid       # real directory
Defensive patterns

Strategy: validation

Validate before calling

fn run_dir_ok(p: &std::path::Path) -> bool {
    match std::fs::symlink_metadata(p) {
        Ok(m) => m.is_dir() && !m.file_type().is_symlink(),
        Err(e) => e.kind() == std::io::ErrorKind::NotFound, // created later
    }
}

Try / catch

match astrid_home.validate() {
    Err(e) if e.kind() == std::io::ErrorKind::InvalidData && e.to_string().contains("not a real directory") => {
        // fix or clear ASTRID_RUN_DIR, then retry
    },
    other => other?,
}

Prevention

When it happens

Trigger: Setting ASTRID_RUN_DIR to a path that already exists as a regular file, socket, fifo, or device node; calling AstridHome validation (configured_path/validate) while a stale file occupies the intended run-dir path.

Common situations: A leftover lockfile or pidfile was left at the run-dir path by a previous crashed run; an operator set ASTRID_RUN_DIR=/var/run/astrid.pid by mistake; a container volume mounted a file where a directory was expected.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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