uutils/coreutils · error · clap::Error

realpath-invalid-empty-operand

Error message

realpath-invalid-empty-operand

What it means

realpath rejects an empty string operand at argument-parse time via a custom clap ValueValidation error carrying the localized 'realpath-invalid-empty-operand' message. POSIX realpath requires a non-empty path operand, so passing '' (e.g. from an unquoted empty variable) is invalid input rather than a filesystem error.

Solutions

1. Quote and validate variables before use: ensure the path argument is non-empty before calling realpath.
2. Provide a default path in scripts: realpath "${1:?path required}".
3. Fix the upstream producer that emits an empty value (missing env var, failed command substitution).
4. Use `${VAR:?}` or `: "${VAR:?}"` guards to fail early with a clear message.

Example fix

#!/bin/sh
# before: realpath "$TARGET" -> error when TARGET empty
# after: fail early with a clear message
: "${TARGET:?TARGET must be set to a non-empty path}"
realpath "$TARGET"

#!/bin/sh
: "${TARGET:?TARGET must be a non-empty path}"
[ -n "$TARGET" ] || { echo "empty path" >&2; exit 1; }
realpath "$TARGET"

function isValidPathOperand(v) {
  return typeof v === 'string' && v.length > 0;
}

const { status, stderr } = spawnSync('realpath', [target]);
if (status !== 0 && /empty/i.test(stderr.toString())) {
  console.error('realpath: empty operand — check the variable feeding the argument');
}

When it happens

Trigger: Invoking `realpath ""` directly, or `realpath "$VAR"` where VAR is unset/empty; scripting patterns like `realpath "$1"` when the positional argument is missing; --relative-to/-- combinations fed an empty value through the custom value parser (parse_ref).

Common situations: Shell scripts where a variable was never set (missing config/env); functions taking a path parameter called without arguments; pipelines producing empty output consumed as a path argument.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• invalid value
• InvalidUtf8
• Is a directory
• mv-error-backup-might-destroy-source
• mv-error-dangling-symlink

AI-assisted analysis of uutils/coreutils@92995feca2 (2026-09-20). Data as JSON: /api/errors/fc505aa82d23182c. Report an issue: GitHub.

Appendix: source

Thrown at src/uu/realpath/src/realpath.rs:54

const OPT_RELATIVE_BASE: &str = "relative-base";

const ARG_FILES: &str = "files";

/// Custom parser that validates `OsString` is not empty
#[derive(Clone, Debug)]
struct NonEmptyOsStringParser;

impl TypedValueParser for NonEmptyOsStringParser {
    type Value = OsString;

    fn parse_ref(
        &self,
        _cmd: &Command,
        _arg: Option<&Arg>,
        value: &OsStr,
    ) -> Result<Self::Value, clap::Error> {
        if value.is_empty() {
            let mut err = clap::Error::new(clap::error::ErrorKind::ValueValidation);
            err.insert(
                clap::error::ContextKind::Custom,
                clap::error::ContextValue::String(translate!("realpath-invalid-empty-operand")),
            );
            return Err(err);
        }
        Ok(value.to_os_string())
    }
}

impl ValueParserFactory for NonEmptyOsStringParser {
    type Parser = Self;

    fn value_parser() -> Self::Parser {
        Self
    }
}

View on GitHub (pinned to 92995feca2)