puppeteer/puppeteer · error · ArchiverUnavailableError

Extraction failed: The optional `yauzl` dependency is not in

Error message

Extraction failed: The optional `yauzl` dependency is not installed.

What it means

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.

Source

Thrown at packages/browsers/src/fileUtil.ts:232

    }
  }
  throw new Error(
    `Extraction failed: no zip archiver is available. Install \`unzip\` (or \`tar.exe\`/Powershell on Windows), or add the optional \`yauzl\` dependency.`,
  );
}

/**
 * @internal
 */
export async function extractZipWithYauzl(
  archivePath: string,
  folderPath: string,
  _logger?: Logger,
): Promise<void> {
  const {default: yauzl} = await import(
    /* webpackIgnore: true */ 'yauzl'
  ).catch(() => {
    throw new ArchiverUnavailableError(
      'Extraction failed: The optional `yauzl` dependency is not installed.',
    );
  });
  const open = promisify<string, Options, ZipFile>(yauzl.open);
  try {
    const zipFile = await open(archivePath, {lazyEntries: true});
    await new Promise((resolve, reject) => {
      zipFile
        .on('error', reject)
        .on('end', resolve)
        .on('entry', entry => {
          extractZipEntry(zipFile, entry, folderPath).then(() => {
            zipFile.readEntry();
          }, reject);
        })
        .readEntry();
    });
  } catch (error) {

View on GitHub (pinned to d484e21c17)

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.

Example fix

// before
await extractZipWithYauzl(archive, dest); // throws if yauzl absent

// after
npm install yauzl
// or: use the higher-level extractZip which tries CLI first
await extractZip(archive, dest);

Defensive patterns

Strategy: fallback

Validate before calling

function yauzlInstalled(): boolean {
  try { require.resolve('yauzl'); return true; } catch { return false; }
}

if (!yauzlInstalled()) {
  throw new Error('yauzl is not installed. Run `npm install yauzl` or use extractZip (CLI fallback).');
}

Try / catch

try {
  await extractZipWithYauzl(archive, dest);
} catch (e) {
  if ((e as Error).message.includes('yauzl')) {
    await extractZipWithCli(archive, dest); // CLI fallback
    return;
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: Slim installs that omitted the optional dep; bundlers (webpack/esbuild) that need /* webpackIgnore: true */ honored; calling the internal function directly in tests.

Related errors

AI-assisted analysis of puppeteer/puppeteer@d484e21c17 (2026-08-12). Data as JSON: /api/errors/ec4a777629730c8c. Report an issue: GitHub.