jackwener/OpenCLI · error · ArgumentError

flathub ${label} cannot be empty

Error message

flathub ${label} cannot be empty

What it means

requireString validates that a user-supplied string argument (labelled, e.g. 'query') is non-empty after trimming; otherwise it throws ArgumentError with 'flathub <label> cannot be empty'. The library throws this early to fail fast before making any network request with an unusable value.

Source

Thrown at clis/flathub/utils.js:19

// Shared helpers for the Flathub adapters (https://flathub.org).
//
// Flathub is the canonical Linux flatpak app registry. Public REST API at
// `flathub.org/api/v2`, no auth, no key. Two endpoints we surface:
//   • POST /search      → keyword search, returns app metadata
//   • GET  /appstream/<appId> → full appstream metadata for one app
import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';

export const FLATHUB_API_BASE = 'https://flathub.org/api/v2';
export const FLATHUB_APP_BASE = 'https://flathub.org/apps';
const UA = 'opencli-flathub-adapter/1.0 (+https://github.com/jackwener/opencli; mailto:opencli@example.com)';

// AppStream IDs are reverse-DNS (e.g. "org.gnome.Calculator"); the spec allows
// letters, digits, `.`, `_`, `-`. Min two segments separated by `.`.
const APP_ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_][A-Za-z0-9_-]*){1,}$/;

export function requireString(value, label) {
    const s = String(value ?? '').trim();
    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")');

View on GitHub (pinned to 49907e53dc)

Solutions

1. Supply a non-empty value for the argument (e.g. the search query)
2. Check the variable feeding the argument is actually set before calling
3. Trim and validate inputs in your script before invoking the adapter
4. If using CLI flags, pass the value explicitly rather than relying on defaults

Example fix

// before
const query = process.env.QUERY; // may be undefined
await searchApps(query);
// after
const query = (process.env.QUERY ?? '').trim();
if (!query) throw new Error('QUERY env var is required');
await searchApps(query);

function isNonEmptyString(v) {
  return typeof v === 'string' && v.trim().length > 0;
}
if (!isNonEmptyString(query)) throw new Error('query must be a non-empty string');

function isNonEmptyString(v) {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  await searchApps(query);
} catch (err) {
  if (err instanceof ArgumentError && /cannot be empty/.test(err.message)) {
    console.error(`Missing required argument: ${err.message}`);
    process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Calling an adapter that calls requireString(value, label) with null, undefined, '', whitespace-only, or a value coercing to '' (e.g. requireString(query) where query comes from an unset CLI flag or empty env var).

Common situations: CLI invoked with a missing positional argument; shell variable expansion producing an empty string ($QUERY unset); passing an empty object/string from a script; trailing-whitespace-only input.

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

• 1688 item expects an offer URL or offer ID
• 1688 store expects a store URL or member ID
• Invalid 1688 URL
• tid must be a numeric thread id
• kind

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