jackwener/OpenCLI · error · ArgumentError

flathub appId is required (e.g. "org.mozilla.firefox")

Error message

flathub appId is required (e.g. "org.mozilla.firefox")

What it means

requireAppId validates the Flathub appId argument and throws ArgumentError 'flathub appId is required (e.g. "org.mozilla.firefox")' when the value is empty after trimming. The library throws this early because every app-detail lookup requires a non-empty AppStream ID to build the API URL.

Source

Thrown at clis/flathub/utils.js:37

    if (!s) throw new ArgumentError(`flathub ${label} cannot be empty`);
    return s;
}

export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
    const raw = value ?? defaultValue;
    const n = typeof raw === 'number' ? raw : Number(raw);
    if (!Number.isInteger(n) || n <= 0) {
        throw new ArgumentError(`flathub ${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`flathub ${label} must be <= ${maxValue}`);
    }
    return n;
}

export function requireAppId(value) {
    const raw = String(value ?? '').trim();
    if (!raw) throw new ArgumentError('flathub appId is required (e.g. "org.mozilla.firefox")');
    if (!APP_ID_PATTERN.test(raw)) {
        throw new ArgumentError(
            `flathub appId "${value}" is not a valid AppStream identifier`,
            'AppStream IDs use reverse-DNS like "org.mozilla.firefox" — letters/digits/`._-` with at least one dot.',
        );
    }
    return raw;
}

export async function flathubFetch(url, label, init) {
    let resp;
    try {
        resp = await fetch(url, {
            method: init?.method ?? 'GET',
            headers: { 'user-agent': UA, accept: 'application/json', ...(init?.headers ?? {}) },
            body: init?.body,
        });
    }

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a valid appId such as org.mozilla.firefox
2. Find the exact ID via `flathub search <name>` and use its appId field
3. Check that the shell variable feeding the argument is set and exported
4. Default the value in your script and fail with a clear message before calling

Example fix

// before
const id = process.argv[3]; // missing
await appInfo(id);
// after
const id = process.argv[3];
if (!id) {
  console.error('usage: flathub info <appId>  e.g. org.mozilla.firefox');
  process.exit(2);
}
await appInfo(id);

const id = (appId ?? '').trim();
if (!id) throw new Error('appId is required, e.g. org.mozilla.firefox');

function hasAppId(args) {
  return typeof args.appId === 'string' && args.appId.trim().length > 0;
}

try {
  await appInfo(appId);
} catch (err) {
  if (err instanceof ArgumentError && err.message.includes('appId is required')) {
    console.error('usage: flathub info <appId>  e.g. org.mozilla.firefox');
    process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Calling an adapter that calls requireAppId(value) with null, undefined, '', or whitespace, e.g. `flathub info` with no appId argument, or requireAppId(env.APP_ID) with the variable unset.

Common situations: CLI invoked without the positional appId; shell variable unset or empty when interpolated; piping an empty line into a script; copy-paste losing the argument.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• <train-no> must not be empty
• keyword must not be empty
• <from> station must not be empty
• <to> station must not be empty
• who 不能为空

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