{"record":{"id":"fec5ca8cef08783b","repo":"jackwener/OpenCLI","slug":"failed-to-download-item-filename-result-erro","errorCode":null,"errorMessage":"Failed to download ${item.filename}: ${result.error || 'unknown error'}","messagePattern":"Failed to download (.+?): (.+?)","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/instagram/download.js","lineNumber":332,"sourceCode":"        throw new AuthRequiredError('instagram.com', message);\n    }\n    if (result.errorCode === 'RATE_LIMITED') {\n        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);\n    }\n    if (result.errorCode === 'PRIVATE_OR_UNAVAILABLE') {\n        throw new CommandExecutionError(message, 'Open the post in a logged-in browser session and retry');\n    }\n    throw new CommandExecutionError(message);\n}\nasync function downloadInstagramMedia(items, outputDir) {\n    fs.mkdirSync(outputDir, { recursive: true });\n    for (const item of items) {\n        const destPath = path.join(outputDir, item.filename);\n        const result = await httpDownload(item.url, destPath, {\n            timeout: item.type === 'video' ? 120000 : 60000,\n        });\n        if (!result.success) {\n            throw new CommandExecutionError(`Failed to download ${item.filename}: ${result.error || 'unknown error'}`);\n        }\n        if (!Number.isFinite(result.size) || result.size <= 0) {\n            throw new CommandExecutionError(`Failed to verify downloaded bytes for ${item.filename}`);\n        }\n    }\n}\ncli({\n    site: 'instagram',\n    name: 'download',\n    access: 'read',\n    description: 'Download images and videos from Instagram posts and reels',\n    domain: 'www.instagram.com',\n    strategy: Strategy.COOKIE,\n    navigateBefore: false,\n    args: [\n        { name: 'url', positional: true, required: true, help: 'Instagram post / reel / tv URL' },\n        { name: 'path', default: '~/Downloads/Instagram', help: 'Download directory' },\n    ],","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/instagram/download.js#L314-L350","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run the command so fresh CDN URLs are fetched (signed URLs expire)","Increase the timeout or check network stability for large videos","Verify the Instagram CDN domains are not blocked by proxy/firewall","Retry later if Instagram CDN is having an outage"],"exampleFix":"// before\nconst result = await httpDownload(item.url, destPath, { timeout: 60000 });\n// after\nconst result = await httpDownload(item.url, destPath, { timeout: 300000, retries: 3 });","handlingStrategy":"retry","validationCode":"// preflight: confirm CDN reachability\nconst ok = await fetch(item.url, { method: 'HEAD' }).then(r => r.ok).catch(() => false);\nif (!ok) throw new Error('Media CDN URL unreachable: ' + item.url);","typeGuard":null,"tryCatchPattern":"try {\n  await downloadInstagramMedia(items, dir);\n} catch (e) {\n  if (String(e.message).startsWith('Failed to download ')) {\n    // refetch metadata to get fresh signed CDN URLs, then retry once\n  } else throw e;\n}","preventionTips":["Re-fetch metadata right before downloading so signed CDN URLs are fresh","Allow longer timeouts for videos (the code uses 120s; raise for slow links)","Ensure proxies/firewalls permit *.cdninstagram.com domains","Download sequentially rather than hammering the CDN in parallel"],"tags":["instagram","network","download-failure","timeout","cdn"],"backgroundTag":"media-download-failed","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}