{"record":{"id":"ec4a777629730c8c","repo":"puppeteer/puppeteer","slug":"extraction-failed-the-optional-yauzl-dependency","errorCode":null,"errorMessage":"Extraction failed: The optional `yauzl` dependency is not installed.","messagePattern":"Extraction failed: The optional `yauzl` dependency is not installed\\.","errorType":"exception","errorClass":"ArchiverUnavailableError","httpStatus":null,"severity":"error","filePath":"packages/browsers/src/fileUtil.ts","lineNumber":232,"sourceCode":"    }\n  }\n  throw new Error(\n    `Extraction failed: no zip archiver is available. Install \\`unzip\\` (or \\`tar.exe\\`/Powershell on Windows), or add the optional \\`yauzl\\` dependency.`,\n  );\n}\n\n/**\n * @internal\n */\nexport async function extractZipWithYauzl(\n  archivePath: string,\n  folderPath: string,\n  _logger?: Logger,\n): Promise<void> {\n  const {default: yauzl} = await import(\n    /* webpackIgnore: true */ 'yauzl'\n  ).catch(() => {\n    throw new ArchiverUnavailableError(\n      'Extraction failed: The optional `yauzl` dependency is not installed.',\n    );\n  });\n  const open = promisify<string, Options, ZipFile>(yauzl.open);\n  try {\n    const zipFile = await open(archivePath, {lazyEntries: true});\n    await new Promise((resolve, reject) => {\n      zipFile\n        .on('error', reject)\n        .on('end', resolve)\n        .on('entry', entry => {\n          extractZipEntry(zipFile, entry, folderPath).then(() => {\n            zipFile.readEntry();\n          }, reject);\n        })\n        .readEntry();\n    });\n  } catch (error) {","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/puppeteer/puppeteer/blob/d484e21c17f6023826fefdcdeeb553e04a7aaed8/packages/browsers/src/fileUtil.ts#L214-L250","documentation":"Thrown by extractZipWithYauzl when the dynamic import('yauzl') rejects (module not installed). It is an ArchiverUnavailableError, intentionally a separate class so extractZip can catch it and try the next strategy rather than aborting. End users normally only see it if they call extractZipWithYauzl directly.","triggerScenarios":"Calling extractZipWithYauzl without `yauzl` in node_modules; package.json never listed yauzl; a monorepo hoist removed it; the dynamic import is blocked by a bundler at runtime.","commonSituations":"Slim installs that omitted the optional dep; bundlers (webpack/esbuild) that need /* webpackIgnore: true */ honored; calling the internal function directly in tests.","solutions":["Install yauzl: npm install yauzl.","If you do not want yauzl, call extractZip (which falls back to the CLI) instead of extractZipWithYauzl directly.","Ensure your bundler respects the /* webpackIgnore: true */ comment so the import stays external."],"exampleFix":"// before\nawait extractZipWithYauzl(archive, dest); // throws if yauzl absent\n\n// after\nnpm install yauzl\n// or: use the higher-level extractZip which tries CLI first\nawait extractZip(archive, dest);","handlingStrategy":"fallback","validationCode":"function yauzlInstalled(): boolean {\n  try { require.resolve('yauzl'); return true; } catch { return false; }\n}\n\nif (!yauzlInstalled()) {\n  throw new Error('yauzl is not installed. Run `npm install yauzl` or use extractZip (CLI fallback).');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await extractZipWithYauzl(archive, dest);\n} catch (e) {\n  if ((e as Error).message.includes('yauzl')) {\n    await extractZipWithCli(archive, dest); // CLI fallback\n    return;\n  }\n  throw e;\n}","preventionTips":["Prefer the high-level extractZip over the yauzl-specific entry point.","List yauzl in dependencies if you call extractZipWithYauzl directly.","Ensure bundlers honor /* webpackIgnore: true */ so the dynamic import stays external."],"tags":["extraction","zip","yauzl","dependencies"],"backgroundTag":null,"analyzedSha":"d484e21c17f6023826fefdcdeeb553e04a7aaed8","analyzedAt":"2026-08-12T06:33:19.665Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}