jackwener/OpenCLI · error · ArgumentError

username is required

Error message

username is required

What it means

normalizeUsername trims the input and strips leading '@' characters, then throws this ArgumentError if nothing remains. The CLI requires a concrete handle for user-scoped commands and will not proceed with a blank value.

Source

Thrown at clis/tiktok/utils.js:44

    if (!Number.isInteger(parsed) || parsed <= 0) {
        throw new ArgumentError(
            `${name} must be a positive integer`,
            `Example: --${name} ${fallback}`,
        );
    }
    if (parsed > max) {
        throw new ArgumentError(
            `${name} must be <= ${max}`,
            `Example: --${name} ${max}`,
        );
    }
    return parsed;
}

export function normalizeUsername(value) {
    const username = String(value ?? '').trim().replace(/^@+/, '');
    if (!username) {
        throw new ArgumentError(
            'username is required',
            'Example: opencli tiktok following <username>',
        );
    }
    if (!/^[A-Za-z0-9._-]+$/.test(username)) {
        throw new ArgumentError(
            'username contains unsupported characters',
            'Pass the TikTok handle without @, for example: dictogo',
        );
    }
    return username;
}

export const NOTIFICATION_TYPES = {
    all: { code: 0, label: 'all' },
    likes: { code: 3, label: 'likes' },
    comments: { code: 7, label: 'comments' },
    mentions: { code: 6, label: 'mentions' },

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass the handle as a positional argument, e.g. opencli tiktok following dictogo.
2. Pass at least one usable character after '@' stripping ('@user' is fine, '@' alone is not).
3. Fix unset/empty shell variables with "${USER_NAME:?username required}".
4. In code, validate the value is a non-empty trimmed string before calling.

Example fix

// before
const user = process.env.TT_USER; // undefined
await cli.tiktok.following(user); // throws
// after
const user = process.env.TT_USER;
if (!user || !String(user).replace(/^@+/, '').trim()) throw new Error('set TT_USER');
await cli.tiktok.following(user);

function requireHandle(v) {
  const handle = String(v ?? '').trim().replace(/^@+/, '');
  if (!handle) throw new Error('username is required: pass e.g. dictogo');
  return handle;
}
requireHandle(process.argv[2]);

const hasUsername = (v) => typeof v === 'string' && v.trim().replace(/^@+/, '').length > 0;

try {
  await cli.tiktok.following(username);
} catch (e) {
  if (e.message === 'username is required') {
    console.error('Usage: opencli tiktok following <username>');
    process.exitCode = 2;
  } else throw e;
}

When it happens

Trigger: Omitting the <username> positional argument entirely; passing only '@' or '@@'; passing an empty string, null, or undefined; a shell variable expanding to empty (USER_NAME="").

Common situations: Scripted invocations where the username variable is unset; copy-pasting a command template without filling the placeholder; piping arguments incorrectly so the positional arg is dropped.

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
• Either --product-id or --url is required
• --city is required (numeric city ID from `ctrip search` or `
• --${name} is required (e.g. 北京 / 上海)
• hotel id is required (numeric id from `ctrip hotel-suggest`,

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