jackwener/OpenCLI · error · ArgumentError

lichess username is required

Error message

lichess username is required

What it means

This ArgumentError is thrown by `requireUsername` when the username argument is missing, empty, or only whitespace after `String(value ?? '').trim()`. The library requires a non-empty handle before making any Lichess API call.

Source

Thrown at clis/lichess/utils.js:24

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

export const LICHESS_BASE = 'https://lichess.org';
const UA = 'opencli-lichess-adapter/1.0 (+https://github.com/jackwener/opencli; mailto:opencli@example.com)';

// Lichess usernames are 2-30 chars: letters, digits, underscore, dash. Case-insensitive.
const USERNAME_PATTERN = /^[A-Za-z0-9_-]{2,30}$/;

// `perfType` values lichess accepts for the `/api/player/top/<n>/<perf>` endpoint.
// Source: lichess-org/api docs.
export const LICHESS_PERFS = new Set([
    'ultraBullet', 'bullet', 'blitz', 'rapid', 'classical',
    'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde',
    'kingOfTheHill', 'racingKings', 'threeCheck',
]);

export function requireUsername(value) {
    const raw = String(value ?? '').trim();
    if (!raw) throw new ArgumentError('lichess username is required');
    if (!USERNAME_PATTERN.test(raw)) {
        throw new ArgumentError(
            `lichess username "${value}" is not a valid handle`,
            'Allowed: letters, digits, underscore, dash; length 2-30.',
        );
    }
    return raw;
}

export function requirePerf(value) {
    const raw = String(value ?? '').trim();
    if (!raw) throw new ArgumentError('lichess perf is required (e.g. "blitz", "bullet", "rapid")');
    if (!LICHESS_PERFS.has(raw)) {
        throw new ArgumentError(
            `lichess perf "${value}" is not recognised`,
            `Allowed values: ${[...LICHESS_PERFS].join(', ')}.`,
        );
    }

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a non-empty username to the command/argument
2. Check the value before calling: trim it and verify it is truthy
3. Fix the source of the empty value (env var, config key, script variable)
4. Use `--help` to confirm the command's expected argument order

Example fix

// before
await username(''); // ArgumentError: lichess username is required
// after
const name = process.env.PLAYER?.trim();
if (!name) throw new Error('PLAYER env var must be set');
await username(name);

function assertUsernameProvided(v) {
  const s = String(v ?? '').trim();
  if (!s) throw new TypeError('username is required');
  return s;
}
assertUsernameProvided(cliArgs.username);

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

try {
  await username(args[0]);
} catch (e) {
  if (e instanceof ArgumentError && /username is required/.test(e.message)) {
    console.error('Usage: lichess user <username>');
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Calling `username()` (or any command routed through `requireUsername`) with `undefined`, `null`, `''`, or a whitespace-only string for the username parameter.

Common situations: Forgetting the CLI positional argument; an env-var or config value that resolves to empty; scripting where a variable was never set; shell quoting issues yielding an empty string.

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

• lichess perf is required (e.g. "blitz", "bullet", "rapid")
• <train-no> must not be empty
• keyword must not be empty
• <from> station must not be empty
• <to> station must not be empty

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