can1357/oh-my-pi · error · StatError

cannot stat {file}: {error}

Error message

cannot stat {file}: {error}

What it means

This error (crates/pi-builtins/src/stat.rs, CannotStat) is the generic failure of the stat builtin's default file mode: the stat/lstat call on the given path failed. The wrapped `error` contains the OS reason (usually ENOENT, EACCES, or ELOOP). This is the most common stat error and mirrors GNU stat's `cannot stat 'file'` message.

Source

Thrown at crates/pi-builtins/src/stat.rs:150

for details about the options it supports.";

	#[derive(Debug, Error)]
	enum StatError {
		#[error("Invalid quoting style: {style}")]
		InvalidQuotingStyle { style: String },
		#[error("missing operand\nTry 'stat --help' for more information.")]
		MissingOperand,
		#[error("{directive}: invalid directive")]
		InvalidDirective { directive: String },
		#[error("cannot read table of mounted file systems: {error}")]
		#[cfg_attr(not(unix), allow(dead_code, reason = "mount tables are unix-only"))]
		CannotReadFilesystem { error: String },
		#[error("using '-' to denote standard input does not work in file system mode")]
		#[cfg_attr(not(unix), allow(dead_code, reason = "stdin filesystem mode is unix-only"))]
		StdinFilesystemMode,
		#[error("cannot read file system information for {file}: {error}")]
		CannotReadFilesystemInfo { file: String, error: String },
		#[error("cannot stat {file}: {error}")]
		CannotStat { file: String, error: String },
	}

	mod options {
		pub const DEREFERENCE: &str = "dereference";
		pub const FILE_SYSTEM: &str = "file-system";
		pub const FORMAT: &str = "format";
		pub const PRINTF: &str = "printf";
		pub const TERSE: &str = "terse";
		pub const BSD_SHELL: &str = "bsd-shell";
		pub const BSD_TIMEFMT: &str = "bsd-timefmt";
		pub const FILES: &str = "files";
	}

	#[derive(Default, Debug, PartialEq, Eq, Clone, Copy)]
	struct Flags {
		alter: bool,
		zero:  bool,

View on GitHub (pinned to 9690622007)

Solutions

1. Verify the path exists and is spelled correctly (`ls -ld <file>`).
2. Check permissions on every path component (need execute bit on directories): `namei -l <path>`.
3. If it is a symlink, inspect `readlink <file>`; use the dereference option (`-L`) as appropriate.
4. Handle the error in scripts: use `stat <file> ||` fallback so missing files don't abort pipelines.

Example fix

// before
stat /tmp/missing-file.txt  // cannot stat /tmp/missing-file.txt: No such file or directory

// after
ls -ld /tmp/missing-file.txt || echo "file absent; creating"
touch /tmp/missing-file.txt
stat /tmp/missing-file.txt

import { statSync } from 'node:fs';
function pathIsStatable(p) {
  try { statSync(p); return true; } catch { return false; }
}

function isCannotStatError(err) {
  return err instanceof Error && err.message.startsWith('cannot stat ');
}

try {
  await stat.run([path]);
} catch (err) {
  if (String(err).startsWith('cannot stat ')) {
    console.error(`skipping unreachable path ${path}: ${err}`);
  } else throw err;
}

When it happens

Trigger: Calling the stat utility with a path that does not exist, lacks a path-component's execute (search) permission, sits on an unreachable mount, or triggers symlink loops.

Common situations: Typos in the filename; running as a user without directory traversal permissions; a dangling symlink when not using dereference-aware logic; deleted files referenced by stale paths in scripts.

Related errors

• {}: {error}
• cannot stat {0}: No such file or directory
• cannot stat {0}: Not a directory
• inter-device move failed: {} to {}; unable to remove target:
• Permission denied

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/a22178863a3778e6. Report an issue: GitHub.