jackwener/OpenCLI · error · ArgumentError

crates ${label} cannot be empty

Error message

crates ${label} cannot be empty

What it means

requireString rejects empty/whitespace-only values for any labeled crates argument. If the stringified, trimmed value is empty it throws this ArgumentError with the label interpolated (e.g. 'crates query cannot be empty'). It guarantees downstream fetches never run with a blank query.

Source

Thrown at clis/crates/utils.js:12

// Shared helpers for the crates.io adapters.
import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';

export const CRATES_BASE = 'https://crates.io';
const UA = 'opencli-crates-adapter (+https://github.com/jackwener/opencli)';

// crates.io crate names: 1-64 chars, ascii letters/digits/-_, must start with a letter.
const CRATE_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;

export function requireString(value, label) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError(`crates ${label} cannot be empty`);
    return s;
}

export function requireCrateName(value) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError('crates crate name is required (e.g. "serde", "tokio")');
    if (!CRATE_NAME.test(s)) {
        throw new ArgumentError(
            `crates crate name "${value}" is not a valid crates.io name`,
            'Names start with an ASCII letter, then 0-63 chars of letters / digits / "_-".',
        );
    }
    return s;
}

export function requireBoundedInt(value, defaultValue, maxValue, label = 'limit') {
    const raw = value ?? defaultValue;
    const n = typeof raw === 'number' ? raw : Number(raw);

View on GitHub (pinned to 49907e53dc)

Solutions

1. Provide a non-empty query, e.g. --query "serde".
2. If the value comes from a variable or env var, check it is non-empty before invoking.
3. Pre-validate: if (!query?.trim()) throw/handle before calling the API.
4. Fix shell quoting so the flag is not collapsed to an empty argument.

Example fix

// before
const q = process.env.SEARCH_TERM ?? ''; // '' when unset
await cli.crates.search({ query: q });
// after
const q = process.env.SEARCH_TERM;
if (!q || !q.trim()) throw new Error('SEARCH_TERM is required');
await cli.crates.search({ query: q.trim() });

function nonEmpty(value, label) {
  const s = String(value ?? '').trim();
  if (!s) throw new Error(`${label} cannot be empty`);
  return s;
}
const query = nonEmpty(process.argv.query, 'query');

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

try {
  await cli.crates.search({ query });
} catch (e) {
  if (e instanceof ArgumentError && e.message.includes('cannot be empty')) {
    console.error('Usage: crates search --query <term>');
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Calling `crates search` with query set to '', ' ', null, or undefined; any CLI invocation where a required string flag was omitted or shell quoting collapsed it to nothing.

Common situations: Forgetting to pass --query in a script, environment-variable interpolation expanding to an empty string, an empty string in a config file, or shell word-splitting stripping whitespace-only arguments.

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

• station must not be empty
• ${label} cannot be empty
• crates crate name is required (e.g. "serde", "tokio")
• crates crate name "${value}" is not a valid crates.io name
• crates ${label} must be a positive integer

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