{"record":{"id":"8535e107d07a6ac0","repo":"apify/crawlee","slug":"savesnapshot-with-key-key-failed-cause-err-8535e1","errorCode":null,"errorMessage":"saveSnapshot with key ${key} failed.\nCause:${(err as Error).message}","messagePattern":"saveSnapshot with key (.+?) failed\\.\nCause:(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts","lineNumber":777,"sourceCode":"        });\n\n        if (saveScreenshot) {\n            const screenshotName = `${key}.jpg`;\n            const screenshotBuffer = await page.screenshot({\n                fullPage: true,\n                quality: screenshotQuality,\n                type: 'jpeg',\n            });\n            await store.setValue(screenshotName, screenshotBuffer, { contentType: 'image/jpeg' });\n        }\n\n        if (saveHtml) {\n            const htmlName = `${key}.html`;\n            const html = await page.content();\n            await store.setValue(htmlName, html, { contentType: 'text/html' });\n        }\n    } catch (err) {\n        throw new Error(`saveSnapshot with key ${key} failed.\\nCause:${(err as Error).message}`);\n    }\n}\n\nexport interface PuppeteerContextUtils {\n    /**\n     * Injects a JavaScript file into current `page`.\n     * Unlike Puppeteer's `addScriptTag` function, this function works on pages\n     * with arbitrary Cross-Origin Resource Sharing (CORS) policies.\n     *\n     * File contents are cached for up to 10 files to limit file system access.\n     */\n    injectFile(filePath: string, options?: InjectFileOptions): Promise<unknown>;\n\n    /**\n     * Injects the [jQuery](https://jquery.com/) library into current `page`.\n     * jQuery is often useful for various web scraping and crawling tasks.\n     * For example, it can help extract text from HTML elements using CSS selectors.\n     *","sourceCodeStart":759,"sourceCodeEnd":795,"githubUrl":"https://github.com/apify/crawlee/blob/dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c/packages/puppeteer-crawler/src/internals/utils/puppeteer_utils.ts#L759-L795","documentation":"saveSnapshot() captures the page's screenshot and/or HTML content into a KeyValueStore, and wraps any failure (page.screenshot, page.content, or store.setValue throwing) in this single error that names the snapshot key and the underlying cause. It is a wrapper so the original error's message is preserved after 'Cause:'.","triggerScenarios":"Calling saveSnapshot({ page, key, saveHtml/savePng }) when the underlying store write fails (KeyValueStore unavailable, invalid key characters), the browser/page is closed or crashed before capture, page.content() fails on a detached/navigating frame, or screenshot times out on a hung page.","commonSituations":"Snapshotting in a finally block after a page crash, invalid keys containing path separators, slow pages exceeding the default screenshot timeout, and browser disconnected mid-crawl.","solutions":["Read the 'Cause:' suffix to find the real error and fix that root cause first","Validate the snapshot key (no '/', '\\\\', or other invalid KeyValueStore characters)","Pass explicit options like screenshot timeout: saveSnapshot({ ..., timeout: 60000 })","Check that the browser/page is still open before snapshotting (page.isClosed())","Ensure the KeyValueStore (local or cloud) is writable and credentials/quota are fine"],"exampleFix":"// before\nawait saveSnapshot({ page, key });\n// after\ntry {\n    await saveSnapshot({ page, key, savePng: true, saveHtml: true, timeout: 60_000 });\n} catch (err) {\n    getLog().warning(`Snapshot ${key} skipped: ${err.message}`);\n}","handlingStrategy":"try-catch","validationCode":"function canSnapshot(page, key) {\n    return typeof page?.content === 'function' && !page.isClosed?.() && key && !/[\\\\/:*?\"<>|]/.test(key);\n}","typeGuard":"const isValidSnapshotInput = (input) =>\n    input && typeof input.page?.content === 'function' && typeof input.key === 'string' && input.key.length > 0;","tryCatchPattern":"try {\n    await saveSnapshot({ page, key, savePng: true, saveHtml: true });\n} catch (err) {\n    log.warning(`snapshot ${key} skipped: ${err.message.split('Cause:')[1] ?? err.message}`);\n}","preventionTips":["Never let a snapshot failure crash the crawl — treat snapshots as best-effort","Validate keys before use (no path separators)","Give screenshots a generous timeout for slow pages","Check page.isClosed() before capturing"],"tags":["puppeteer","snapshot","key-value-store","error-wrapping"],"backgroundTag":"snapshot-save-failed","analyzedSha":"dbe57fb09ca607ad59dcf998f3925ef9ac3bb26c","analyzedAt":"2026-08-30T22:22:28.328Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}