jackwener/OpenCLI · error · ArgumentError

dockerhub ${label} cannot be empty

Error message

dockerhub ${label} cannot be empty

What it means

requireString validates that a labeled CLI argument is a non-empty string after trimming. This ArgumentError is thrown when the value is missing, null, undefined, or whitespace-only. It guards API calls against empty query parameters.

Source

Thrown at clis/dockerhub/utils.js:18

// Shared helpers for the Docker Hub adapters.
//
// Hits the public, unauthenticated `hub.docker.com/v2` REST endpoints. Anonymous
// pulls are throttled but search / metadata reads are friendly enough for
// ad-hoc CLI use. Image names follow `[<owner>/]<name>` with `library` as the
// implicit owner for Docker official images.
import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';

export const HUB_BASE = 'https://hub.docker.com/v2';
const UA = 'opencli-dockerhub-adapter (+https://github.com/jackwener/opencli)';

// Docker Hub repository slugs are 2-255 chars, lowercase alphanumerics + `_.-`,
// optionally prefixed with a Docker Hub user/org of the same charset.
const SLUG = /^[a-z0-9][a-z0-9._-]*$/;

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

/**
 * Split an image identifier into `{owner, name}`. Bare names use the implicit
 * `library` owner that Docker Hub uses for official images (`nginx` →

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Provide the required --query value
  2. Check that the shell variable feeding the flag is non-empty
  3. Trim/validate user input before passing it to the CLI

Example fix

// before
dockerhub search --query "$TERM"   # TERM unset -> empty
// after
: "${TERM:?TERM must be set}" && dockerhub search --query "$TERM"
Defensive patterns

Strategy: validation

Validate before calling

const query = (args.query ?? '').trim(); if (!query) throw new Error('--query must be a non-empty string');

Type guard

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

Try / catch

try { await search(args); } catch (e) { if (e instanceof ArgumentError && e.message.includes('cannot be empty')) { console.error(`Missing required --${e.message.replace('dockerhub ','').replace(' cannot be empty','')}`); process.exitCode = 2; } else throw e; }

Prevention

When it happens

Trigger: Calling dockerhub search (or any command using requireString(args.query,'query')) without --query; passing --query '' or --query ' '; an unset shell variable expanding to nothing.

Common situations: Scripts where the search term variable is empty; forgetting a required flag in CI pipelines; copy-pasting a command with a placeholder left in quotes.

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

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