ScreenshotNeo
Sign in Get a free key

BlogEngineering

Puppeteer CommandOptions Explained

Puppeteer’s CommandOptions reference lists one property, timeout, but leaves its behavior unspecified. Learn how it differs from the documented browser launch timeout.

By the ScreenshotNeo team4 October 20265 min read

Direct answer: In Puppeteer v25.12.0, CommandOptions documents one property: timeout: number. Its API reference does not explain what operation it applies to, its units, or its default. Do not assume it behaves like LaunchOptions.timeout, which is a separate, documented setting for waiting for a browser to start.

This distinction matters when troubleshooting automation: the launch timeout has a defined meaning, but the checked CommandOptions reference does not establish equivalent semantics for its property. The official sources are the CommandOptions API reference, the LaunchOptions API reference, and the PuppeteerNode.launch() documentation.

What is Puppeteer CommandOptions?

CommandOptions is an interface in Puppeteer’s v25.12.0 API reference. The property table lists only timeout, with type number. The reference leaves the description and default blank; it does not state the unit or identify which command or operation consumes it.

Property Type Documented purpose Documented default
timeout number Not specified on the reference page Not specified

That is the reliable answer to “What does Puppeteer CommandOptions timeout do?” based on the checked API page: the page does not define the behavior. Avoid assigning it milliseconds, a specific operation, or a default based on another Puppeteer timeout.

CommandOptions.timeout vs. LaunchOptions.timeout

LaunchOptions.timeout is a distinct setting passed to browser launch. Puppeteer documents it as the maximum time, in milliseconds, to wait for the browser to start. Its listed default is 30,000 ms (30 seconds), and 0 disables that launch timeout.

Setting What the reference says What not to infer
CommandOptions.timeout Numeric property; purpose, unit, and default are unspecified on its API page. Do not infer launch behavior or milliseconds from its name.
LaunchOptions.timeout Maximum milliseconds to wait for browser startup; default 30,000 ms; 0 disables the timeout. Do not treat this documented launch setting as a definition of CommandOptions.timeout.

If Chrome takes too long to start, configure the launch option in the object passed to puppeteer.launch(). Changing an unrelated value called timeout elsewhere does not establish that the launch limit changed.

Runnable example: configure the documented launch timeout

The following Node.js example uses Puppeteer’s launch option. It does not rely on undocumented CommandOptions semantics. Install Puppeteer with npm install puppeteer; the standard package downloads and uses a specific Chrome version by default.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    timeout: 60_000, // milliseconds to wait for browser startup
    headless: true,
  });

  try {
    const page = await browser.newPage();
    await page.goto('https://example.com');
    console.log(await page.title());
  } finally {
    await browser.close();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Set timeout to the maximum startup wait in milliseconds. Use 0 only if you deliberately want no launch timeout; without a limit, a stalled startup can wait indefinitely from the caller’s perspective.

Launch configuration that commonly affects startup

LaunchOptions contains more than the timeout. The options relevant to browser selection and startup include:

  • executablePath: path to a browser executable. Puppeteer says compatibility is guaranteed only with its bundled browser; for an external executable, set browser as well.
  • channel: selects a browser channel. Users of puppeteer-core must provide either executablePath or channel to launch().
  • browser: identifies the browser type; useful alongside an external executable.
  • headless: true selects new headless mode; 'shell' selects old headless mode.
  • devtools: enabling DevTools forces headless to false.
  • args: additional browser command-line arguments.
  • ignoreDefaultArgs: removes selected default arguments or, if used to disable all defaults, can change expected launch behavior. Puppeteer cautions that it should be used carefully.
  • userDataDir: browser profile directory.
  • pipe and debuggingPort: browser connection choices.
  • env, signal, dumpio, and waitForInitialPage: additional launch controls documented in the API reference.

For the full current option list and types, see the LaunchOptions reference. The configuration guide explains that standard Puppeteer downloads a specific Chrome version and that executablePath can select another Chrome or Chromium binary. It also notes that Puppeteer configuration files and environment variables are ignored by puppeteer-core.

Choosing puppeteer or puppeteer-core

Use puppeteer when you want Puppeteer’s normal browser download and bundled compatibility baseline. Use puppeteer-core when your environment manages the browser binary or channel; its launch call requires executablePath or channel.

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/chrome',
    browser: 'chrome',
    timeout: 30_000,
  });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com');
    console.log(await page.title());
  } finally {
    await browser.close();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Replace the example path with a real executable available to the process. If using an installed browser rather than Puppeteer’s bundled Chrome for Testing, version compatibility is your responsibility.

Practical troubleshooting

Symptom Likely cause What to do
Browser launch rejects after about 30 seconds. The documented launch timeout is at its 30,000 ms default. Check whether browser startup is slow or blocked. If a longer startup window is appropriate, raise LaunchOptions.timeout in milliseconds.
puppeteer-core cannot launch a browser. No browser executable or channel was supplied. Provide executablePath or channel to launch().
An external Chrome binary behaves unexpectedly. Puppeteer guarantees compatibility with its bundled browser, not arbitrary external versions. Prefer the bundled Chrome for Testing build, or verify the external binary and specify browser with executablePath.
DevTools opens despite headless: true. devtools: true forces headless mode off. Disable DevTools when headless operation is required.
Browser startup changes after setting ignoreDefaultArgs. Removing defaults can discard arguments Puppeteer normally supplies. Remove only the specific default argument needed; avoid disabling all defaults unless you know the consequences.
A CommandOptions.timeout value has no clear effect. The checked API page does not describe its operation, units, or default. Identify the API that accepts the object and consult that API’s documentation or type definitions for its own version. Do not substitute assumptions from LaunchOptions.timeout.

Performance, reliability, and cost considerations

A launch timeout is a limit on waiting for startup; increasing it gives slow launches more time but does not itself make them faster. If a browser repeatedly approaches the limit, check browser availability, executable selection, environment configuration, and launch arguments. Use the bundled browser where practical to stay within Puppeteer’s documented compatibility baseline.

Setting the launch timeout to 0 removes that safeguard, so make sure the surrounding job or service has its own way to stop stuck work. The API documentation does not establish a performance, reliability, or cost impact for CommandOptions.timeout; those depend on the specific command using that interface and its implementation.

Or skip the browser setup

If the task is to capture a website rather than control a local browser, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

FAQ

What is the default for CommandOptions.timeout?

The v25.12.0 CommandOptions reference does not specify a default.

Is CommandOptions.timeout measured in milliseconds?

The checked reference does not state a unit. Milliseconds are documented for LaunchOptions.timeout, which is a different property.

What is Puppeteer’s default launch timeout?

LaunchOptions.timeout defaults to 30,000 milliseconds, or 30 seconds. Setting it to 0 disables that timeout.

Does puppeteer-core download Chrome?

The launch documentation requires a browser channel or executable path for puppeteer-core. Configuration files and environment variables used by Puppeteer are ignored by that package.

Keep reading