{"record":{"id":"753ab8c733903731","repo":"jackwener/OpenCLI","slug":"flathub-appid-value-is-not-a-valid-appstream","errorCode":null,"errorMessage":"flathub appId \"${value}\" is not a valid AppStream identifier","messagePattern":"flathub appId \"(.+?)\" is not a valid AppStream identifier","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"clis/flathub/utils.js","lineNumber":39,"sourceCode":"}\n\nexport function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {\n    const raw = value ?? defaultValue;\n    const n = typeof raw === 'number' ? raw : Number(raw);\n    if (!Number.isInteger(n) || n <= 0) {\n        throw new ArgumentError(`flathub ${label} must be a positive integer`);\n    }\n    if (n > maxValue) {\n        throw new ArgumentError(`flathub ${label} must be <= ${maxValue}`);\n    }\n    return n;\n}\n\nexport function requireAppId(value) {\n    const raw = String(value ?? '').trim();\n    if (!raw) throw new ArgumentError('flathub appId is required (e.g. \"org.mozilla.firefox\")');\n    if (!APP_ID_PATTERN.test(raw)) {\n        throw new ArgumentError(\n            `flathub appId \"${value}\" is not a valid AppStream identifier`,\n            'AppStream IDs use reverse-DNS like \"org.mozilla.firefox\" — letters/digits/`._-` with at least one dot.',\n        );\n    }\n    return raw;\n}\n\nexport async function flathubFetch(url, label, init) {\n    let resp;\n    try {\n        resp = await fetch(url, {\n            method: init?.method ?? 'GET',\n            headers: { 'user-agent': UA, accept: 'application/json', ...(init?.headers ?? {}) },\n            body: init?.body,\n        });\n    }\n    catch (err) {\n        throw new CommandExecutionError(","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/flathub/utils.js#L21-L57","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the full reverse-DNS AppStream ID, e.g. org.mozilla.firefox not firefox","Run `flathub search <name>` and copy the appId field from the result","If you pasted a URL, extract just the last path segment as the appId","Trim the value and strip stray characters before calling"],"exampleFix":"// before\nawait appInfo('firefox');\n// after\nawait appInfo('org.mozilla.firefox');","handlingStrategy":"validation","validationCode":"const APP_ID_RE = /^[A-Za-z][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_][A-Za-z0-9_-]*){1,}$/;\nconst id = (appId ?? '').trim();\nif (!APP_ID_RE.test(id)) throw new Error(`\"${appId}\" is not a valid AppStream ID`);","typeGuard":"function isValidAppId(v) {\n  return typeof v === 'string' && /^[A-Za-z][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_][A-Za-z0-9_-]*){1,}$/.test(v.trim());\n}","tryCatchPattern":"try {\n  await appInfo(appId);\n} catch (err) {\n  if (err instanceof ArgumentError && err.message.includes('not a valid AppStream identifier')) {\n    console.error(err.message + ' — ' + (err.hint ?? 'use reverse-DNS like org.mozilla.firefox'));\n    process.exitCode = 2;\n  } else throw err;\n}","preventionTips":["Always use the full reverse-DNS ID from `flathub search` output, never the bare app name","Strip URL prefixes when users paste Flathub links","Validate IDs with the AppStream regex at input boundaries","Watch for stray whitespace/invisible characters in copied IDs"],"tags":["argument-validation","format-validation","appstream-id"],"backgroundTag":"invalid-identifier-format","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}