jackwener/OpenCLI · error · ArgumentError

URL must follow /@<username>/video/<id> format

Error message

URL must follow /@<username>/video/<id> format

What it means

The URL must be the canonical /@<username>/video/<numeric-id> path. Share links (vm.tiktok.com/...), bare video IDs, and other tiktok.com paths are explicitly out of scope, so the pathname regex /\/^\/@([A-Za-z0-9._-]+)\/video\/(\d+)\/?$/ failing produces this ArgumentError.

Source

Thrown at clis/tiktok/utils.js:129

    }
    let parsed;
    try {
        parsed = new URL(raw);
    } catch {
        throw new ArgumentError(
            `invalid video URL: ${raw}`,
            'Example: https://www.tiktok.com/@user/video/1234567890',
        );
    }
    if (!/(^|\.)tiktok\.com$/i.test(parsed.hostname)) {
        throw new ArgumentError(
            `URL must be on tiktok.com (got ${parsed.hostname})`,
            'Example: https://www.tiktok.com/@user/video/1234567890',
        );
    }
    const match = parsed.pathname.match(/^\/@([A-Za-z0-9._-]+)\/video\/(\d+)\/?$/);
    if (!match) {
        throw new ArgumentError(
            'URL must follow /@<username>/video/<id> format',
            'Example: https://www.tiktok.com/@user/video/1234567890',
        );
    }
    return {
        url: parsed.toString(),
        username: match[1],
        videoId: match[2],
    };
}

export function looksTikTokAuthFailure(message) {
    return /\bAUTH_REQUIRED\b|\b(auth|captcha|login|log in|permission|unauthori[sz]ed|forbidden)\b|HTTP\s+(401|403)\b/i.test(String(message || ''));
}

export function looksTikTokUpstreamFailure(message) {
    return /\b(API failed|HTTP\s+\d+|invalid JSON|Failed to fetch|network|fetch)\b/i.test(String(message || ''));
}

View on GitHub (pinned to 49907e53dc)

Solutions

1. Open the share link in a browser and copy the resolved canonical /@user/video/<id> URL
2. Verify the path matches /@<username>/video/<numeric id> (note the @ prefix)
3. Strip query strings is not required (they are allowed), but ensure the pathname itself is the canonical video path

Example fix

// before
parseTikTokVideoUrl('https://vm.tiktok.com/ZMabc123/')
// after
parseTikTokVideoUrl('https://www.tiktok.com/@user/video/1234567890')

const u = new URL(value); if (!/^\/@[A-Za-z0-9._-]+\/video\/\d+\/?$/.test(u.pathname)) throw new Error('not a canonical /@user/video/<id> URL');

const isCanonicalTikTokVideoUrl = (v) => { try { return /^\/@[A-Za-z0-9._-]+\/video\/\d+\/?$/.test(new URL(String(v)).pathname); } catch { return false; } };

try { parseTikTokVideoUrl(url); } catch (e) { if (/format/.test(e.message)) console.error('Resolve share links to /@user/video/<id> first'); else throw e; }

When it happens

Trigger: Passing a valid https tiktok.com URL whose pathname is not /@user/video/<digits> — e.g. vm.tiktok.com/abc123 share links, /t/ links, photo posts (/photo/<id>), or a video ID with non-digit characters.

Common situations: Copying a share link from the mobile app; URL-encoding or trailing junk in the path; username containing characters outside [A-Za-z0-9._-]; passing a video ID instead of a full URL.

Related errors

• archive search sort must be one of ${SORT_OPTIONS.join(', ')
• archive search mediatype must be one of ${MEDIATYPES.join(',
• archive search limit must be a positive integer
• archive search limit must be <= 100
• archive search query must not be empty

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