jackwener/OpenCLI · error · CommandExecutionError

Failed to download ${item.filename}: ${result.error || 'unkn

Error message

Failed to download ${item.filename}: ${result.error || 'unknown error'}

What it means

downloadInstagramMedia downloads each media item with httpDownload; if the download reports result.success === false, the library throws this CommandExecutionError including the item's filename and the underlying error (or 'unknown error'). It means the binary fetch of the media file from Instagram's CDN failed, separate from the metadata phase which already succeeded.

Source

Thrown at clis/instagram/download.js:332

        throw new AuthRequiredError('instagram.com', message);
    }
    if (result.errorCode === 'RATE_LIMITED') {
        throw new CliError('RATE_LIMITED', message, 'Wait a few minutes and retry, or switch to a browser session with a warmer Instagram login state.', EXIT_CODES.TEMPFAIL);
    }
    if (result.errorCode === 'PRIVATE_OR_UNAVAILABLE') {
        throw new CommandExecutionError(message, 'Open the post in a logged-in browser session and retry');
    }
    throw new CommandExecutionError(message);
}
async function downloadInstagramMedia(items, outputDir) {
    fs.mkdirSync(outputDir, { recursive: true });
    for (const item of items) {
        const destPath = path.join(outputDir, item.filename);
        const result = await httpDownload(item.url, destPath, {
            timeout: item.type === 'video' ? 120000 : 60000,
        });
        if (!result.success) {
            throw new CommandExecutionError(`Failed to download ${item.filename}: ${result.error || 'unknown error'}`);
        }
        if (!Number.isFinite(result.size) || result.size <= 0) {
            throw new CommandExecutionError(`Failed to verify downloaded bytes for ${item.filename}`);
        }
    }
}
cli({
    site: 'instagram',
    name: 'download',
    access: 'read',
    description: 'Download images and videos from Instagram posts and reels',
    domain: 'www.instagram.com',
    strategy: Strategy.COOKIE,
    navigateBefore: false,
    args: [
        { name: 'url', positional: true, required: true, help: 'Instagram post / reel / tv URL' },
        { name: 'path', default: '~/Downloads/Instagram', help: 'Download directory' },
    ],

View on GitHub (pinned to 49907e53dc)

Solutions

1. Re-run the command so fresh CDN URLs are fetched (signed URLs expire)
2. Increase the timeout or check network stability for large videos
3. Verify the Instagram CDN domains are not blocked by proxy/firewall
4. Retry later if Instagram CDN is having an outage

Example fix

// before
const result = await httpDownload(item.url, destPath, { timeout: 60000 });
// after
const result = await httpDownload(item.url, destPath, { timeout: 300000, retries: 3 });

// preflight: confirm CDN reachability
const ok = await fetch(item.url, { method: 'HEAD' }).then(r => r.ok).catch(() => false);
if (!ok) throw new Error('Media CDN URL unreachable: ' + item.url);

try {
  await downloadInstagramMedia(items, dir);
} catch (e) {
  if (String(e.message).startsWith('Failed to download ')) {
    // refetch metadata to get fresh signed CDN URLs, then retry once
  } else throw e;
}

When it happens

Trigger: httpDownload fails for a specific media URL — CDN returns 403 (expired/signed URL), network timeout (60s images / 120s videos), DNS failure, or the media URL points to a host the environment can't reach.

Common situations: Slow connection exceeding the per-file timeout, especially for large videos; CDN URLs expiring between metadata fetch and download; corporate proxy/firewall blocking Instagram CDN domains (cdninstagram.com); transient network drop mid-download.

Related errors

• FETCH_ERROR
• archive wayback request failed: ${error?.message || error}
• Bilibili creator comparison
• Bilibili relation modify did not verify ${expectedLabel}; la
• Boss API request failed: ${message}

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