jackwener/OpenCLI · error · ArgumentError

username is required

Error message

username is required

What it means

parseUsername normalizes a username or profile URL to a bare Pinterest username (Pinterest has no @-handles). It throws this ArgumentError when the raw input is empty or whitespace-only after String coercion, since no username can be derived. This fails fast instead of issuing an API request with a blank path segment.

Source

Thrown at clis/pinterest/utils.js:95

  // Pinterest percent-encodes non-ASCII slugs in the URLs it hands out; the API wants them decoded.
  const parts = pathname.split('/').filter(Boolean).map(decodeSegment);
  if (parts.length < 2) return null;
  const [username, slug] = parts;
  if (RESERVED_PATH_ROOTS.has(username.toLowerCase())) {
    throw new ArgumentError(
      `"${raw}" is a Pinterest /${username}/ URL, not a board`,
      username.toLowerCase() === 'pin'
        ? 'Pass the board this pin lives on, e.g. janedoe/my-board (`opencli pinterest pin <id>` reports it)'
        : 'Pass <username>/<slug>, a board URL, or a numeric board id',
    );
  }
  return { username, slug, path: `/${username}/${slug}/` };
}

/** Normalize a username or profile URL to a bare username (Pinterest has no @-handles). */
export function parseUsername(raw) {
  let value = String(raw ?? '').trim();
  if (!value) throw new ArgumentError('username is required', 'Pass a Pinterest username or profile URL, e.g. janedoe');
  if (/^https?:\/\//i.test(value)) {
    try {
      value = decodeSegment(new URL(value).pathname.split('/').filter(Boolean)[0] || '');
    } catch {
      throw new ArgumentError(`Invalid profile URL: ${raw}`, 'Use a full profile URL like https://www.pinterest.com/janedoe/');
    }
  }
  value = value.replace(/^\/+|\/+$/g, '');
  if (!value) throw new ArgumentError(`Not a username: "${raw}"`, 'Pass the bare username, e.g. janedoe');
  if (value.includes('/')) {
    throw new ArgumentError(
      `Not a username: "${raw}"`,
      'This looks like a board or pin reference — pass just the username, e.g. janedoe',
    );
  }
  if (value.startsWith('@')) {
    throw new ArgumentError(`Pinterest usernames have no "@": "${raw}"`, 'Drop the @ and use the bare username, e.g. janedoe');
  }

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a Pinterest username or profile URL, e.g. janedoe or https://www.pinterest.com/janedoe/
2. Check that the environment variable / config key supplying the username is actually set
3. Trim the value before calling so whitespace-only input is caught as a config bug
4. Add an early guard in your script that errors when the username variable is empty

Example fix

// before
const user = parseUsername(process.env.PINTEREST_USER);
// after
const raw = process.env.PINTEREST_USER;
if (!raw || !raw.trim()) throw new Error('Set PINTEREST_USER first');
const user = parseUsername(raw);

const raw = process.env.PINTEREST_USER;
if (!raw || !raw.trim()) {
  throw new Error('PINTEREST_USER is not set');
}

const isNonEmptyString = (v) => typeof v === 'string' && v.trim().length > 0;

let username;
try {
  username = parseUsername(input);
} catch (err) {
  if (err instanceof ArgumentError && err.message === 'username is required') {
    console.error('Usage: ... <username|profile-url>');
    process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Calling parseUsername(''), parseUsername(null), parseUsername(undefined), or parseUsername(' ') — either directly or through a username command whose argument was omitted.

Common situations: Forgot to pass the CLI argument; an env var like $PINTEREST_USER was unset so the shell substituted nothing; a script variable defaulted to 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

• symbol is required
• <username> is required
• <game-url> is required
• Either --product-id or --url is required
• --city is required (numeric city ID from `ctrip search` or `

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