jackwener/OpenCLI · error · ArgumentError

<username> is required

Error message

<username> is required

What it means

An ArgumentError thrown by validateUsername when the username argument is missing, empty, or only whitespace. The library normalizes input with String(value ?? '').trim().toLowerCase() and rejects it before any network call, since a username is mandatory for every player-based Chess.com endpoint.

Source

Thrown at clis/chess/utils.js:23

import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';

export const API_BASE = 'https://api.chess.com/pub';
export const UA = 'Mozilla/5.0 (compatible; opencli/1.0)';

const USERNAME_RE = /^[a-zA-Z0-9_-]{3,25}$/;
const GAME_URL_RE = /^https:\/\/www\.chess\.com\/game\/(live|daily)\/(\d+)/i;

export function isPlainObject(value) {
    return value !== null && typeof value === 'object' && !Array.isArray(value);
}

function isOptionalPlainObject(value) {
    return value === undefined || value === null || isPlainObject(value);
}

export function validateUsername(value) {
    const s = String(value ?? '').trim().toLowerCase();
    if (!s) throw new ArgumentError('<username> is required');
    if (!USERNAME_RE.test(s)) {
        throw new ArgumentError(`Invalid Chess.com username "${value}"`, 'Usernames are 3-25 chars: a-z, 0-9, hyphen, underscore.');
    }
    return s;
}

export function parseGameUrl(value) {
    const s = String(value ?? '').trim();
    if (!s) throw new ArgumentError('<game-url> is required');
    const m = s.match(GAME_URL_RE);
    if (!m) {
        throw new ArgumentError(
            `Invalid Chess.com game URL: "${value}"`,
            'Expected https://www.chess.com/game/live/<id> or https://www.chess.com/game/daily/<id>.',
        );
    }
    return { kind: m[1].toLowerCase(), id: m[2] };
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a non-empty username string, e.g. opencli chess stats --username hikaru.
2. Check the env var or config value feeding the argument is set before calling.
3. Add a CLI-level required-argument check so the user gets usage help instead of this error.

Example fix

// before
const stats = await chessStats({ username: process.env.CHESS_USER });
// after
if (!process.env.CHESS_USER) throw new Error('CHESS_USER env var is required');
const stats = await chessStats({ username: process.env.CHESS_USER });

function requireUsername(value) {
  const s = String(value ?? '').trim();
  if (!s) throw new Error('username is required before calling the chess API');
  return s;
}

function hasUsername(args) {
  return typeof args.username === 'string' && args.username.trim().length > 0;
}

try {
  const rows = await chessStats({ username });
} catch (e) {
  if (e.name === 'ArgumentError' && /username is required/i.test(e.message)) {
    console.error('Usage: opencli chess stats --username <name>');
  } else throw e;
}

When it happens

Trigger: Calling stats/archives/monthly commands with username undefined, null, an empty string, or a value that trims to nothing (e.g. ' ').

Common situations: A required CLI flag not passed; reading a username from an unset environment variable or config key that yields undefined; passing null programmatically.

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

• symbol is required
• <game-url> is required
• Either --product-id or --url is required
• --city is required (numeric city ID from `ctrip search` or `
• --${name} is required (e.g. 北京 / 上海)

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