Puppeteer 20 AbortSignal: aborted navigations reject with generic Error instead of TimeoutError

The Discrepancy

Since Puppeteer 20.0.0, methods like page.goto, page.waitForNavigation, and page.waitForSelector accept an AbortSignal as the first argument. This allows for cancelling in-flight work using an AbortController. However, a discrepancy exists: when a timeout is triggered via page.setDefaultNavigationTimeout or the timeout option, Puppeteer rejects with a TimeoutError. When the same operation is cancelled via AbortSignal, it rejects with a generic Error('The operation was aborted').

Why It Matters

Test harnesses and retry logic often branch on instanceof TimeoutError to distinguish between a slow page and a functional failure. Receiving a generic Error on an abort forces developers to use string matching on the error message, which is brittle and prone to breaking during library updates.

Resolution Strategy

To handle this safely across Puppeteer versions, you should check the state of the AbortController rather than relying on the error class or message string.

const controller = new AbortController();

try {
  await page.goto('https://example.com', { signal: controller.signal });
} catch (error) {
  if (controller.signal.aborted) {
    // Handle intentional cancellation (no retry)
    console.log('Navigation was aborted by user');
  } else if (error.name === 'TimeoutError') {
    // Handle timeout (potential retry)
    handleTimeout();
  } else {
    // Handle other actual failures
    throw error;
  }
}

Assumptions and Uncertainties

• It is assumed you are using Puppeteer v20.x where the AbortSignal support was introduced.
• It is uncertain whether a dedicated AbortError class is planned for future releases to align with standard Web API-AbortError behavior.
• Matching on the string The operation was aborted is considered not safe across minor versions, as internal error messages can change without version increments.