apify/crawlee · error · Error

Experimental containers are only available with Playwright

Error message

Experimental containers are only available with Playwright

What it means

Experimental containers is a Playwright-specific LaunchContext feature. When launching with Puppeteer, the plugin checks for it and refuses to launch if enabled, because Puppeteer has no equivalent container support.

Source

Thrown at packages/browser-pool/src/puppeteer/puppeteer-plugin.ts:70

        } catch {
            // ignore
        }

        const { useIncognitoPages, proxyUrl, ignoreProxyCertificate } = launchContext;

        let browser: PuppeteerTypes.Browser;

        if (this.remoteConnection) {
            browser = await this.connectToRemoteBrowser(launchContext, async (url) => {
                const connectOptions = this.remoteConnectionParameters?.connectOptions ?? {};
                this.log.info('Connecting to remote browser via connect (CDP).');
                return this.library.connect({ ...connectOptions, browserWSEndpoint: url });
            });
        } else {
            const { launchOptions, userDataDir, experimentalContainers } = launchContext;

            if (experimentalContainers) {
                throw new Error('Experimental containers are only available with Playwright');
            }

            launchOptions!.userDataDir = launchOptions!.userDataDir ?? userDataDir;

            if (launchOptions!.headless === false) {
                if (Array.isArray(launchOptions!.args)) {
                    launchOptions!.args.push('--disable-site-isolation-trials');
                } else {
                    launchOptions!.args = ['--disable-site-isolation-trials'];
                }
            }

            if (launchOptions!.headless === true && oldPuppeteerVersion) {
                launchOptions!.headless = 'new' as any;
            }

            {
                const [anonymizedProxyUrl, close] = await anonymizeProxySugar(proxyUrl, undefined, undefined, {

View on GitHub (pinned to dbe57fb09c)

Solutions

Set experimentalContainers: false (or remove it) from the LaunchContext used with PuppeteerPlugin.
Use a separate LaunchContext per engine: enable experimentalContainers only in the Playwright LaunchContext.
Switch to PlaywrightPlugin if browser containers are a hard requirement.

Example fix

// before
new PuppeteerPlugin(new LaunchContext({ puppeteer, experimentalContainers: true }));
// after
new PuppeteerPlugin(new LaunchContext({ puppeteer })); // containers are Playwright-only
// or use PlaywrightPlugin to keep experimentalContainers: true

Defensive patterns

Strategy: validation

Validate before calling

const lc = new LaunchContext({ puppeteer, experimentalContainers: false });
if (usingPuppeteer && lc.experimentalContainers) {
  throw new Error('experimentalContainers requires PlaywrightPlugin');
}

Type guard

function containersSupported(plugin: 'puppeteer' | 'playwright', lc: { experimentalContainers?: boolean }): boolean {
  return plugin === 'playwright' || !lc.experimentalContainers;
}

Try / catch

try {
  await pool.init();
} catch (err) {
  if (err instanceof Error && err.message.includes('Experimental containers')) {
    // rebuild plugin without experimentalContainers or switch to PlaywrightPlugin
  } throw err;
}

Prevention

Never share a single LaunchContext across Puppeteer and Playwright plugins.
Treat experimentalContainers as Playwright-only in config schema/docs.
Validate engine/feature combinations at config load time, not at pool init.

When it happens

Trigger: Creating PuppeteerPlugin with a LaunchContext that has experimentalContainers: true, then starting the pool (plugin _launch runs).

Common situations: Sharing one LaunchContext/config object between Playwright and Puppeteer setups; toggling experimentalContainers on for testing and switching engines; copy-pasted Playwright config applied to Puppeteer.

Related errors

AI-assisted analysis of apify/crawlee@dbe57fb09c (2026-08-30). Data as JSON: /api/errors/08e676e440c07fef. Report an issue: GitHub.