jackwener/OpenCLI · error · ArgumentError

Instagram URL is required

Error message

Instagram URL is required

What it means

parseInstagramMediaTarget throws an ArgumentError because the input string is empty after trimming (or null/undefined). The download command requires a concrete media target — a post/reel URL or media id — to resolve a media identifier.

Source

Thrown at clis/instagram/download.js:46

}
/** A shortcode is the media id written in Instagram's base64 alphabet. */
export function shortcodeToMediaId(shortcode) {
    const raw = String(shortcode || '');
    if (!raw) return '';
    let mediaId = 0n;
    for (const character of raw) {
        const digit = INSTAGRAM_SHORTCODE_ALPHABET.indexOf(character);
        if (digit < 0) return '';
        mediaId = mediaId * 64n + BigInt(digit);
        if (mediaId > MAX_INSTAGRAM_MEDIA_ID) return '';
    }
    if (mediaId <= 0n) return '';
    return mediaId.toString();
}
export function parseInstagramMediaTarget(input) {
    const raw = String(input || '').trim();
    if (!raw) {
        throw new ArgumentError('Instagram URL is required', 'Expected https://www.instagram.com/p/... or https://www.instagram.com/reel/...');
    }
    let url;
    try {
        url = new URL(raw);
    }
    catch {
        throw new ArgumentError(`Invalid Instagram URL: ${raw}`, 'Expected https://www.instagram.com/p/<shortcode>/ or /reel/<shortcode>/');
    }
    if (!['http:', 'https:'].includes(url.protocol)) {
        throw new ArgumentError(`Unsupported URL protocol: ${url.protocol}`);
    }
    const host = url.hostname.toLowerCase();
    if (host !== INSTAGRAM_HOST_SUFFIX && !host.endsWith(`.${INSTAGRAM_HOST_SUFFIX}`)) {
        throw new ArgumentError(`Unsupported host: ${host}`, 'Only instagram.com URLs are supported');
    }
    const segments = url.pathname.split('/').filter(Boolean);
    let kind;
    let shortcode;

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a full Instagram media URL, e.g. https://www.instagram.com/p/<code>/ or https://www.instagram.com/reel/<code>/
2. Fix the variable/env/config that should contain the URL and confirm it is non-empty before invoking
3. Quote the URL in shells so special characters don't get dropped
4. Add an early check in your script: if (!url) throw ... before calling the CLI

Example fix

// before
instagram download "$IG_URL"
// after
if [ -z "${IG_URL:-}" ]; then echo 'IG_URL is not set'; exit 1; fi
instagram download "$IG_URL"

function requireInstagramUrl(input) {
  const raw = String(input || '').trim();
  if (!raw) throw new Error('Instagram URL is required');
  if (!/^https:\/\/www\.instagram\.com\/(p|reel)\//.test(raw)) {
    throw new Error('Expected https://www.instagram.com/p/... or /reel/... URL');
  }
  return raw;
}

function isInstagramMediaUrl(v) {
  return typeof v === 'string' && /^https:\/\/www\.instagram\.com\/(p|reel)\/[A-Za-z0-9_-]+\//.test(v.trim());
}

try {
  await downloadInstagramMedia(input);
} catch (e) {
  if (e.name === 'ArgumentError' && /Instagram URL is required/.test(e.message)) {
    console.error('Provide a post or reel URL, e.g. https://www.instagram.com/p/<code>/');
  } else throw e;
}

When it happens

Trigger: Calling instagram download with no argument; passing an empty string or whitespace; a variable/placeholder in a script that failed to interpolate; environment/config value unset.

Common situations: Forgetting the URL argument on the CLI; CI scripts where the URL comes from an unset env var; copying only the Instagram page title instead of the URL; shell quoting eating the argument.

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

• index must be a positive integer
• index must be a positive integer
• Collection not found: ' + collectionArg + '. Available: ' +
• archive search sort must be one of ${SORT_OPTIONS.join(', ')
• archive search mediatype must be one of ${MEDIATYPES.join(',

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