jackwener/OpenCLI · error · ArgumentError

homebrew ${label} cannot be empty

Error message

homebrew ${label} cannot be empty

What it means

requireString coerces its argument to a string, trims it, and throws ArgumentError('homebrew <label> cannot be empty') when the result is empty. It enforces that a required textual argument (e.g. a search query) was actually provided by the caller.

Source

Thrown at clis/homebrew/utils.js:18

// Shared helpers for the Homebrew adapters.
//
// Hits the public, unauthenticated `formulae.brew.sh/api` JSON endpoints
// (served as static files from GitHub Pages, regenerated daily). No auth.
// Formula / cask tokens are lowercase ASCII + `-_.+@` per Homebrew's own
// validation; they round-trip into `homebrew formula` / `homebrew cask`.
import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';

export const BREW_BASE = 'https://formulae.brew.sh/api';
const UA = 'opencli-homebrew-adapter (+https://github.com/jackwener/opencli)';

// Homebrew formula / cask tokens — letters / digits / `_-.+@` (`gcc@13`,
// `imagemagick@6`, `c++`, `0-ad`, `php-cs-fixer`).
const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._+@-]*$/;

export function requireString(value, label) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError(`homebrew ${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(`homebrew ${label} must be a positive integer`);
    }
    if (n > maxValue) {
        throw new ArgumentError(`homebrew ${label} must be <= ${maxValue}`);
    }
    return n;
}

export function requireToken(value, label) {
    const s = String(value ?? '').trim();
    if (!s) {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a non-empty query string to the command
2. Check the shell variable/flag actually has a value before invoking
3. Validate arguments in the caller with an early check
4. Handle ArgumentError in the CLI layer with a usage message

Example fix

// before
await homebrewQuery(process.env.Q);
// after
const q = (process.env.Q ?? '').trim();
if (!q) throw new Error('--query is required');
await homebrewQuery(q);

const q = String(rawQuery ?? '').trim();
if (!q) throw new Error(`homebrew query value is required (got: ${JSON.stringify(rawQuery)})`);

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

try {
  await homebrewQuery(rawQuery);
} catch (err) {
  if (err instanceof ArgumentError && /cannot be empty/.test(err.message)) {
    console.error('Usage: homebrew search <query>');
    process.exitCode = 2;
    return;
  }
  throw err;
}

When it happens

Trigger: Calling query('') or query(null)/query(undefined), or passing a CLI flag with no value (e.g. --query "" ) so the trimmed string is empty.

Common situations: Shell variable holding the query is unset/empty, quoting mistake yields an empty argument, or programmatic callers pass undefined fields.

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

• archive search sort must be one of ${SORT_OPTIONS.join(', ')
• archive search mediatype must be one of ${MEDIATYPES.join(',
• archive search limit must be a positive integer
• archive search query must not be empty
• douyin stats aweme_id must be a 16-20 digit numeric ID

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