{"record":{"id":"0e95a58f603ef740","repo":"jackwener/OpenCLI","slug":"instagram-com","errorCode":null,"errorMessage":"instagram.com","messagePattern":"instagram\\.com","errorType":"exception","errorClass":"AuthRequiredError","httpStatus":null,"severity":"error","filePath":"clis/instagram/download.js","lineNumber":314,"sourceCode":"function ensurePage(page) {\n    if (!page)\n        throw new CommandExecutionError('Browser session required');\n    return page;\n}\nfunction normalizeFetchResult(result) {\n    const unwrapped = unwrapEvaluateResult(result);\n    if (!unwrapped || typeof unwrapped !== 'object' || Array.isArray(unwrapped)) {\n        throw new CommandExecutionError('Failed to fetch Instagram media metadata');\n    }\n    if (typeof unwrapped.ok !== 'boolean') {\n        throw new CommandExecutionError('Instagram media metadata returned malformed result');\n    }\n    return unwrapped;\n}\nfunction handleFetchFailure(result) {\n    const message = result.error || 'Instagram media fetch failed';\n    if (result.errorCode === 'AUTH_REQUIRED') {\n        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'}`);","sourceCodeStart":296,"sourceCodeEnd":332,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/instagram/download.js#L296-L332","documentation":"handleFetchFailure maps an AUTH_REQUIRED errorCode from the in-page Instagram metadata fetch into an AuthRequiredError for the instagram.com domain. It means Instagram's API rejected the request because the current browser session has no valid (or any) login cookies, so private/authorized data cannot be fetched. The thrown error carries the site 'instagram.com' plus the API's error message.","triggerScenarios":"The in-page fetch to Instagram's media metadata endpoint returned {ok:false, errorCode:'AUTH_REQUIRED'} — sessionid/csrftoken cookies missing or expired, or Instagram returned 401/403 on the graphql query.","commonSituations":"Cookie store never populated because the user never logged in to Instagram in the automation browser; expired session after Instagram invalidated old cookies; using a fresh browser profile; Instagram logging the session out for suspicious activity.","solutions":["Open a browser session and log in to Instagram so session cookies exist, then re-run the command","Re-authenticate if the session expired (log out/in to refresh sessionid and csrftoken)","Verify cookies are being shared with the automation browser profile (correct user-data-dir)","Avoid rapid automated requests that trigger Instagram's session invalidation"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// before running, confirm a logged-in session exists\nconst loggedIn = await browserPage.evaluate(() => !!document.cookie.match(/sessionid=/));\nif (!loggedIn) throw new Error('Log in to Instagram in the browser session first');","typeGuard":null,"tryCatchPattern":"try {\n  await run(['instagram', 'download', url]);\n} catch (e) {\n  if (e.name === 'AuthRequiredError' && e.site === 'instagram.com') {\n    // open a headed browser session, log in, persist cookies, retry\n  } else throw e;\n}","preventionTips":["Log in once in a persistent browser profile and reuse it","Re-authenticate when sessions expire instead of retrying blindly","Don't share one account across many parallel automation sessions","Watch for Instagram logging sessions out after suspicious activity"],"tags":["instagram","authentication","session-expired","cookies"],"backgroundTag":"instagram-login-required","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}