jackwener/OpenCLI · error · ArgumentError

File not found: ${path}

Error message

File not found: ${path}

What it means

readUtf8File resolves --file input and stats it before reading. If stat() fails (the path does not exist or is inaccessible), it throws ArgumentError 'File not found: <path>' instead of leaking an ENOENT stack trace. This gives CLI users a clean, actionable message.

Source

Thrown at clis/_atlassian/shared.js:298

    if (n > maxValue) {
        throw new ArgumentError(`${label} must be <= ${maxValue}`);
    }
    return n;
}

export function requireExecute(args, commandName) {
    if (args.execute !== true) {
        throw new ArgumentError(`${commandName} requires --execute to perform a remote write`);
    }
}

export async function readUtf8File(filePath) {
    const path = requireString(filePath, '--file');
    let fileStat;
    try {
        fileStat = await stat(path);
    } catch {
        throw new ArgumentError(`File not found: ${path}`);
    }
    if (!fileStat.isFile()) {
        throw new ArgumentError(`File must be a readable text file: ${path}`);
    }
    let raw;
    try {
        raw = await readFile(path);
    } catch {
        throw new ArgumentError(`File could not be read: ${path}`);
    }
    try {
        return new TextDecoder('utf-8', { fatal: true }).decode(raw);
    } catch {
        throw new ArgumentError(`File could not be decoded as UTF-8 text: ${path}`);
    }
}

export function htmlEscape(value) {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Check the path exists (ls / fs.existsSync) and fix typos, then re-run.
2. Run the command from the directory where the file lives, or pass an absolute path.
3. Verify file-system permissions on every path component of the file.

Example fix

// before
cli jira comment --issue PROJ-1 --file ./notes.txt
// after
cli jira comment --issue PROJ-1 --file /home/user/notes.txt  # verified to exist

import { stat } from 'node:fs/promises';
try { await stat(filePath); } catch { throw new Error(`File missing: ${filePath}`); }

const isExistingFile = async (p) => { try { return (await stat(p)).isFile(); } catch { return false; } };

try {
  const text = await readUtf8File(p);
} catch (err) {
  if (err.name === 'ArgumentError' && err.message.startsWith('File not found')) {
    console.error(`Path does not exist: ${p}. Check cwd and spelling.`);
  }
  throw err;
}

When it happens

Trigger: Calling readUtf8File (typically via a --file CLI option) with a path that does not exist, or where a directory component is missing/unsearchable so stat() rejects.

Common situations: Typos in the file path; running from a different working directory than expected; relative path resolved against the wrong cwd in scripts/CI; file deleted between command composition and execution.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• File must be a readable text file: ${path}
• 视频文件不存在: ${videoPath}
• Video file not found: ${resolved}
• Receipt file does not exist: ${receipt}
• ${label} file does not exist: ${ref.value}

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/c80974abce8b6806. Report an issue: GitHub.