jackwener/OpenCLI · error · ArgumentError

lichess username "${value}" is not a valid handle. Allowed:

Error message

lichess username "${value}" is not a valid handle. Allowed: letters, digits, underscore, dash; length 2-30.

What it means

This ArgumentError is thrown by `requireUsername` when the supplied username fails `USERNAME_PATTERN`: only letters, digits, underscore, and dash are allowed, with a length of 2-30. It prevents sending malformed handles to the Lichess API.

Source

Thrown at clis/lichess/utils.js:26

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(', ')}.`,
        );
    }
    return raw;
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Strip protocol/URL parts and leading '@' so only the bare handle is passed
2. Validate the handle against /^[A-Za-z0-9_-]{2,30}$/ before calling
3. Remove illegal characters or correct the typo
4. Note Lichess handles are ASCII-only — transliterate if needed

Example fix

// before
await username('@DrNykterstein'); // invalid: '@' not allowed
// after
const handle = raw.replace(/^@/, '').trim();
if (!/^[A-Za-z0-9_-]{2,30}$/.test(handle)) throw new Error('bad handle');
await username(handle);

const USERNAME_RE = /^[A-Za-z0-9_-]{2,30}$/;
function sanitizeHandle(raw) {
  const s = String(raw ?? '').trim().replace(/^@/, '');
  if (!USERNAME_RE.test(s)) throw new TypeError(`invalid lichess handle: ${raw}`);
  return s;
}
await username(sanitizeHandle(input));

function isValidHandle(v) {
  return typeof v === 'string' && /^[A-Za-z0-9_-]{2,30}$/.test(v);
}

try {
  await username(raw);
} catch (e) {
  if (e instanceof ArgumentError && /not a valid handle/.test(e.message)) {
    console.error('Handles are 2-30 chars: letters, digits, _ or - (no @, spaces, or dots).');
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Calling `username()` (via `requireUsername`) with a value containing spaces, `@`, dots, slashes, or other special characters, or a handle shorter than 2 or longer than 30 characters.

Common situations: Passing a full profile URL or `@mention` instead of the bare handle; including a trailing newline from copy-paste (trimmed, but embedded whitespace fails); test placeholders like 'x'; non-Latin-script usernames being normalized elsewhere.

Related errors

• coingecko currency must look like a currency slug (got "${ar
• designer must be a Dribbble username or profile slug
• lichess username is required
• lichess perf is required (e.g. "blitz", "bullet", "rapid")
• lichess perf "${value}" is not recognised. Allowed values: $

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