jackwener/OpenCLI · error · ArgumentError

Argument "media" is required.

Error message

Argument "media" is required.

What it means

validateMixedMediaItems throws this ArgumentError when the --media value is empty after normalization (normalizePostMediaItems splits kwargs.media on commas and filters empties, leaving zero items). The instagram post command requires at least one media file; an empty list cannot produce a post or carousel, so the library fails fast with usage guidance in the hint argument.

Source

Thrown at clis/instagram/post.js:89

        || (/something went wrong/.test(visibleText) && /try again/.test(visibleText))
      );
      const composerOpen = dialogs.some((dialog) =>
        !!dialog.querySelector('textarea, [contenteditable="true"], input[type="file"]')
        || /write a caption|add location|advanced settings|select from computer|crop|filters|adjustments|sharing/.test((dialog.textContent || '').toLowerCase())
      );
      const settled = !shared && !composerOpen && !/sharing/.test(visibleText);
      return { ok: shared, failed, settled, url: /\\/p\\//.test(url) ? url : '' };
    })()
  `;
}
function requirePage(page) {
    if (!page)
        throw new CommandExecutionError('Browser session required for instagram post');
    return page;
}
function validateMixedMediaItems(inputs) {
    if (!inputs.length) {
        throw new ArgumentError('Argument "media" is required.', 'Provide --media /path/to/file.jpg or --media /path/a.jpg,/path/b.mp4');
    }
    if (inputs.length > MAX_MEDIA_ITEMS) {
        throw new ArgumentError(`Too many media items: ${inputs.length}`, `Instagram carousel posts support at most ${MAX_MEDIA_ITEMS} items`);
    }
    const items = inputs.map((input) => {
        const resolved = path.resolve(String(input || '').trim());
        if (!resolved) {
            throw new ArgumentError('Media path cannot be empty');
        }
        if (!fs.existsSync(resolved)) {
            throw new ArgumentError(`Media file not found: ${resolved}`);
        }
        const ext = path.extname(resolved).toLowerCase();
        if (SUPPORTED_IMAGE_EXTENSIONS.has(ext)) {
            return { type: 'image', filePath: resolved };
        }
        if (SUPPORTED_VIDEO_EXTENSIONS.has(ext)) {
            return { type: 'video', filePath: resolved };

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass at least one existing media file: --media /path/to/file.jpg (or comma-separated list for a carousel).
2. Check the shell variable feeding --media is non-empty before invoking the command.
3. Fix flag typos — the flag is --media, and --media= must be followed by a path.
4. If paths are generated dynamically, guard the command invocation when the file list is empty.
5. Validate media existence/format first so only valid files are passed (see the sibling 'Media file not found' / 'Unsupported media format' errors).

Example fix

// before
const media = process.env.MEDIA_FILES || '';
await run(['instagram', 'post', '--media', media]); // throws if empty
// after
const media = (process.env.MEDIA_FILES || '').trim();
if (!media) throw new Error('MEDIA_FILES must contain at least one file path');
await run(['instagram', 'post', '--media', media]);

const media = String(kwargs.media ?? '').trim();
const items = media.split(',').map(s => s.trim()).filter(Boolean);
if (!items.length) {
  throw new Error('instagram post requires --media with at least one file, e.g. --media /path/to/file.jpg');
}

try {
  await cli.run('instagram post', { media: mediaArg });
} catch (e) {
  if (e instanceof ArgumentError && e.message === 'Argument "media" is required.') {
    console.error('Usage: instagram post --media /path/a.jpg[,/path/b.mp4]');
    process.exitCode = 2; // usage error, not retryable
  } else throw e;
}

When it happens

Trigger: Invoking the instagram post command with no --media flag, --media '' (empty string), --media ',' or ' , ,' (only commas/whitespace), or kwargs.media being whitespace only — all produce an empty inputs array hitting the !inputs.length branch.

Common situations: A script builds the --media list dynamically (e.g. from a glob or variable) and the variable resolves to empty; a shell variable expansion drops the value; typos like --medias or --media= with nothing after the equals sign; CSV paths where all entries were filtered as nonexistent elsewhere upstream.

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

• douyin user-videos requires a sec_uid
• Media path cannot be empty
• lobsters domain is required (e.g. "github.com" or "arxiv.org
• Unknown 12306 station telecode "${trimmed}"
• Unknown 12306 station "${trimmed}"

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