{"record":{"id":"54f98530a692ac91","repo":"jackwener/OpenCLI","slug":"failed-to-fetch-instagram-media-metadata","errorCode":null,"errorMessage":"Failed to fetch Instagram media metadata","messagePattern":"Failed to fetch Instagram media metadata","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/instagram/download.js","lineNumber":304,"sourceCode":"\n      return {\n        ok: true,\n        shortcode: media.code,\n        owner: media?.user?.username || '',\n        items,\n      };\n    })()\n  `;\n}\nfunction 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);","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/instagram/download.js#L286-L322","documentation":"normalizeFetchResult validates the result returned from an in-page script that fetches Instagram media metadata. If unwrapEvaluateResult yields null, a non-object, or an array, the page script failed to produce a usable result envelope, so this CommandExecutionError is thrown instead of continuing with an unusable value. It signals the metadata fetch itself broke, not that Instagram reported a logical failure (that is handled by handleFetchFailure).","triggerScenarios":"browserPage.evaluate() returns null/undefined (page script threw and the wrapper swallowed it), returns a JSON scalar (string/number), or returns an array instead of an {ok, items, ...} object; typically when the page navigated away, the evaluate script was blocked, or the injected script errored before building the result.","commonSituations":"Instagram served a login redirect so the in-page fetch never ran; a page reload or navigation raced the evaluate call; a CSP change or Instagram DOM/API change made the injected script throw; the browser session was closed mid-call.","solutions":["Check the browser session is valid and logged in, then re-run the instagram download command","Retry after ensuring no concurrent navigation happens while the command runs","Update the CLI, since Instagram page/API changes often break the injected fetch script","Wrap or patch buildInstagramFetchScript to always return an {ok:false,error} envelope instead of throwing"],"exampleFix":"// before (injected script can throw, evaluate yields null)\nconst media = await fetchMetadata();\n// after (always return an envelope)\ntry { const media = await fetchMetadata(); return { ok: true, media }; }\ncatch (e) { return { ok: false, errorCode: 'COMMAND_EXEC', error: String(e) }; }","handlingStrategy":"try-catch","validationCode":"if (!page) throw new Error('Browser session required before running instagram download');","typeGuard":"function isFetchEnvelope(r) {\n  return r !== null && typeof r === 'object' && !Array.isArray(r);\n}","tryCatchPattern":"try {\n  const result = normalizeFetchResult(raw);\n} catch (e) {\n  if (String(e.message).includes('Failed to fetch Instagram media metadata')) {\n    // restart browser session and retry once\n  } else throw e;\n}","preventionTips":["Always establish and verify a live browser session before invoking download commands","Avoid navigating or closing the page during evaluate calls","Keep the CLI updated as Instagram page internals change","Log the raw evaluate result when this error occurs to see what actually came back"],"tags":["instagram","browser-automation","malformed-result","puppeteer"],"backgroundTag":"injected-script-returned-null","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}