jackwener/OpenCLI · error · ArgumentError

File could not be decoded as UTF-8 text: ${path}

Error message

File could not be decoded as UTF-8 text: ${path}

What it means

The file is read as raw bytes and decoded with TextDecoder('utf-8', { fatal: true }). If the bytes are not valid UTF-8 (e.g. Latin-1, UTF-16, binary), decoding throws and the function raises ArgumentError 'File could not be decoded as UTF-8 text: <path>'.

Source

Thrown at clis/_atlassian/shared.js:312

    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) {
    return String(value ?? '')
        .replace(/&/g, '&')
        .replace(/</g, '&lt;')
        .replace(/>/g, '&gt;')
        .replace(/"/g, '&quot;');
}

export function htmlToMarkdown(html) {
    return coreHtmlToMarkdown(String(html ?? ''));
}

function applyAdfMarks(text, marks = []) {
    let out = text;
    for (const mark of marks) {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Convert the file to UTF-8 first, e.g. `iconv -f WINDOWS-1252 -t UTF-8 in.txt > out.txt` (detect with `file -i <path>`).
2. Re-save the file as UTF-8 in your editor (VS Code: 'Save with Encoding > UTF-8').
3. Ensure you are passing a text file, not a binary document, to --file.

Example fix

// before
$ file notes.txt
notes.txt: ISO-8859 text
// after
$ iconv -f ISO-8859-1 -t UTF-8 notes.txt > notes-utf8.txt
$ cli jira comment --issue PROJ-1 --file notes-utf8.txt

const raw = await readFile(p);
try { new TextDecoder('utf-8', { fatal: true }).decode(raw); }
catch { throw new Error(`${p} is not valid UTF-8; convert it first`); }

const isUtf8File = async (p) => {
  try { new TextDecoder('utf-8', { fatal: true }).decode(await readFile(p)); return true; }
  catch { return false; }
};

try {
  const text = await readUtf8File(p);
} catch (err) {
  if (err.name === 'ArgumentError' && err.message.includes('UTF-8')) {
    console.error(`Convert ${p} to UTF-8, e.g. iconv -f WINDOWS-1252 -t UTF-8.`);
  }
  throw err;
}

When it happens

Trigger: Passing a file whose bytes are not valid UTF-8: Windows-1252/Latin-1 exports, UTF-16 files with BOM, or binary content (PDF, images, zip) supplied via --file.

Common situations: Files exported from Windows tools in a legacy codepage; files saved as UTF-16 by PowerShell (Out-File default); accidentally passing a binary attachment instead of a text/markdown file.

Related errors

• <train-no> "${trainNo}" does not look like a 12306 internal
• --from station must not be empty
• --to station must not be empty
• --seat-types must contain only 12306 seat letters/digits (A-
• --from and --to must differ; both resolved to ${fromStation.

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