jackwener/OpenCLI · error · ArgumentError

homebrew ${label} "${value}" is not a valid token

Error message

homebrew ${label} "${value}" is not a valid token

What it means

requireToken throws ArgumentError('homebrew <label> "<value>" is not a valid token') (with a hint about allowed characters) when the token is non-empty but fails Homebrew's token charset rules: it must match /^[A-Za-z0-9][A-Za-z0-9._+@-]*$/ and be at most 100 characters.

Source

Thrown at clis/homebrew/utils.js:40

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) {
        throw new ArgumentError(`homebrew ${label} is required (e.g. "wget", "gcc@13", "firefox")`);
    }
    if (s.length > 100 || !TOKEN.test(s)) {
        throw new ArgumentError(
            `homebrew ${label} "${value}" is not a valid token`,
            'Use letters / digits / "_-.+@", starting with a letter or digit (max 100 chars).',
        );
    }
    return s;
}

export function requireOneOf(value, allowed, label) {
    const s = String(value ?? '').trim().toLowerCase();
    if (!s) throw new ArgumentError(`homebrew ${label} is required`);
    if (!allowed.includes(s)) {
        throw new ArgumentError(
            `homebrew ${label} "${value}" is not supported`,
            `Allowed: ${allowed.join(', ')}.`,
        );
    }
    return s;
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Use the bare token only — e.g. `wget`, `gcc@13`, `firefox` — no URLs or paths
2. Strip invalid characters/spaces and retry with a valid token
3. If passing from a shell, quote the token ('gcc@13') to avoid expansion
4. Validate against /^[A-Za-z0-9][A-Za-z0-9._+@-]*$/ before calling

Example fix

// before
await homebrewInfo('https://formulae.brew.sh/formula/wget');
// after
const raw = 'https://formulae.brew.sh/formula/wget';
const token = raw.split('/').filter(Boolean).pop();
await homebrewInfo(token); // 'wget'

const TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9._+@-]*$/;
const token = String(raw ?? '').trim();
if (!TOKEN_RE.test(token) || token.length > 100) {
  throw new Error(`"${raw}" is not a valid Homebrew token (letters/digits/"_-.+@", max 100 chars)`);
}

function isValidBrewToken(v) {
  return typeof v === 'string' && v.length <= 100 &&
    /^[A-Za-z0-9][A-Za-z0-9._+@-]*$/.test(v);
}

try {
  await homebrewInfo(raw);
} catch (err) {
  if (err instanceof ArgumentError && /not a valid token/.test(err.message)) {
    console.error(`${err.message}\n${err.hint ?? ''}`);
    process.exitCode = 2;
    return;
  }
  throw err;
}

When it happens

Trigger: Passing tokens with spaces, slashes, shell globs, or URL-ish input (e.g. 'node.js/' or 'my formula'), tokens starting with a symbol like '@', or >100-char garbage from a bad variable.

Common situations: Users pasting full URLs (https://formulae.brew.sh/formula/wget) instead of the token, copying names with surrounding punctuation, or quoting mistakes splitting 'gcc@13' in shells that expand '@'.

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 limit must be <= 100
• archive search query must not be empty

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