jackwener/OpenCLI · error · ArgumentError

username contains unsupported characters

Error message

username contains unsupported characters

What it means

After the emptiness check, normalizeUsername validates the handle against /^[A-Za-z0-9._-]+$/ and throws this ArgumentError when other characters are present. TikTok handles are restricted to letters, digits, dots, underscores and hyphens, so anything else (slashes, spaces, CJK characters, query strings) is treated as invalid input rather than being passed to the API.

Source

Thrown at clis/tiktok/utils.js:50

    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' },
    followers: { code: 4, label: 'followers' },
};

export function requireNotificationType(value) {
    const key = String(value ?? 'all').trim().toLowerCase();
    if (!Object.prototype.hasOwnProperty.call(NOTIFICATION_TYPES, key)) {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass only the bare handle: 'dictogo', not 'https://www.tiktok.com/@dictogo'.
2. If you have a URL, extract the path segment after '@' before calling (strip anything after '?').
3. Use the canonical @handle shown on the profile, not the display name.
4. Pre-validate with /^[A-Za-z0-9._-]+$/ after trimming and stripping leading '@'.

Example fix

// before
await cli.tiktok.following('https://www.tiktok.com/@dictogo?lang=en'); // throws
// after
const input = 'https://www.tiktok.com/@dictogo?lang=en';
const m = input.match(/@([A-Za-z0-9._-]+)/);
await cli.tiktok.following(m ? m[1] : input);

const HANDLE_RE = /^[A-Za-z0-9._-]+$/;
function toHandle(input) {
  const m = String(input ?? '').match(/@([A-Za-z0-9._-]+)/); // accepts profile URLs too
  const handle = (m ? m[1] : String(input ?? '').trim().replace(/^@+/, ''));
  if (!HANDLE_RE.test(handle)) throw new Error(`not a valid TikTok handle: ${input}`);
  return handle;
}

const isValidHandle = (v) => typeof v === 'string' && /^[A-Za-z0-9._-]+$/.test(v.trim().replace(/^@+/, ''));

try {
  await cli.tiktok.following(rawInput);
} catch (e) {
  if (/unsupported characters/.test(e.message)) {
    console.error('Pass the bare handle (letters, digits, . _ -), not a URL or display name');
  } else throw e;
}

When it happens

Trigger: Passing a full profile URL like https://www.tiktok.com/@user?lang=en; passing a name with spaces or '@' in the middle ('@' is only stripped from the start); passing a display name containing emoji/CJK instead of the canonical handle; accidentally including quotes or shell artifacts.

Common situations: Pasting a URL instead of the handle; using the visible display name (which may contain spaces/emoji) rather than the @handle shown under the avatar; programmatically passing encoded values (%20, +).

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• coingecko derivatives limit must be a positive integer
• ${label} must be a positive integer
• ${label} must be an integer >= ${min}
• medium tag "${value}" is not valid
• ${name} must be a positive integer

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