jackwener/OpenCLI · error · ArgumentError

flathub appId "${value}" is not a valid AppStream identifier

Error message

flathub appId "${value}" is not a valid AppStream identifier

What it means

requireAppId validates the appId against APP_ID_PATTERN (reverse-DNS AppStream ID: letters/digits/._- with at least two dot-separated segments) and throws ArgumentError 'flathub appId "<value>" is not a valid AppStream identifier' on mismatch. This prevents wasted HTTP calls to appstream/<appId> with IDs that can never exist.

Source

Thrown at clis/flathub/utils.js:39

}

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,
        });
    }
    catch (err) {
        throw new CommandExecutionError(

View on GitHub (pinned to 49907e53dc)

Solutions

1. Use the full reverse-DNS AppStream ID, e.g. org.mozilla.firefox not firefox
2. Run `flathub search <name>` and copy the appId field from the result
3. If you pasted a URL, extract just the last path segment as the appId
4. Trim the value and strip stray characters before calling

Example fix

// before
await appInfo('firefox');
// after
await appInfo('org.mozilla.firefox');

const APP_ID_RE = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_][A-Za-z0-9_-]*){1,}$/;
const id = (appId ?? '').trim();
if (!APP_ID_RE.test(id)) throw new Error(`"${appId}" is not a valid AppStream ID`);

function isValidAppId(v) {
  return typeof v === 'string' && /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_][A-Za-z0-9_-]*){1,}$/.test(v.trim());
}

try {
  await appInfo(appId);
} catch (err) {
  if (err instanceof ArgumentError && err.message.includes('not a valid AppStream identifier')) {
    console.error(err.message + ' — ' + (err.hint ?? 'use reverse-DNS like org.mozilla.firefox'));
    process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Calling requireAppId with values like 'firefox' (no dot), 'org.mozilla.firefox!' (invalid chars), '.gnome.calc' (empty leading segment or bad start), or a URL like 'https://flathub.org/apps/org.gnome.Calculator' pasted as the ID.

Common situations: Users passing the plain app name ('firefox') instead of the full reverse-DNS ID; pasting the Flathub web URL; extra spaces or invisible characters in the ID; mixing up app name vs appId from search output.

Related errors

• designer must be a Dribbble username or profile slug
• shot must be a numeric id or dribbble.com/shots URL
• shot URL must match dribbble.com/shots/<id>
• flathub appId is required (e.g. "org.mozilla.firefox")
• hf paper id "${args.id}" is not a valid arXiv id

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