How to Check Whether a Puppeteer Request Is a Navigation Request

Call request.isNavigationRequest() inside a Puppeteer request event handler. It returns true when that request drives navigation of its current frame. It does not tell you whether the request succeeded. The official Puppeteer API reference consulted is labeled version 25.12.0; check the documentation matching your installed package if version compatibility matters.

Minimal check

page.on('request', request => {
  if (request.isNavigationRequest()) {
    console.log('Navigation request:', request.method(), request.url());
  }
});

Puppeteer emits request when a page issues a request, and the callback receives an HTTPRequest. The documented predicate is whether the request drives its current frame’s navigation. Use the method directly; do not infer navigation solely from a URL, HTTP method, or resource type. See the isNavigationRequest() API reference and the HTTPRequest class reference.

Complete runnable example

Install Puppeteer in a Node.js project, save this as check-navigation.js, and run it with node check-navigation.js. Puppeteer’s package includes its supported browser setup. Replace the target URL with a page you are allowed to access.

const puppeteer = require('puppeteer');

async function main() {
  const browser = await puppeteer.launch({ headless: true });

  try {
    const page = await browser.newPage();

    page.on('request', request => {
      const kind = request.isNavigationRequest()
        ? 'navigation'
        : 'subresource or other request';

      console.log(`${kind}: ${request.method()} ${request.url()}`);
    });

    page.on('requestfailed', request => {
      console.error('Request failed:', request.url(), request.failure()?.errorText);
    });

    page.on('requestfinished', request => {
      console.log('Request finished:', request.url());
    });

    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  } finally {
    await browser.close();
  }
}

main().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

The listener is registered before page.goto() so it can observe requests generated during the navigation. The example logs the boolean classification and separately logs request lifecycle events.

What the result means

Check or event	What it answers
request.isNavigationRequest()	Does this request drive navigation of its current frame?
requestfinished	Did the response body download and the request complete?
requestfailed	Did the request fail during its lifecycle?
request.url(), request.method(), request.resourceType()	What URL, method, and perceived resource type does this request have?

Navigation classification and completion are separate. A request can be a navigation request and still fail. Conversely, a false result does not imply the request failed. Puppeteer also documents that HTTP error responses such as 404 or 503 can still complete through requestfinished: an HTTP error status is not the same as a failed request event.

Useful variations and edge cases

Count navigation requests

let navigationCount = 0;

page.on('request', request => {
  if (request.isNavigationRequest()) {
    navigationCount += 1;
    console.log('Navigation number', navigationCount, request.url());
  }
});

This counts requests matching the method’s definition. Redirects issue a new request to the redirected URL, so do not assume one page navigation always produces exactly one request event. The Puppeteer class reference describes redirects as a completed request followed by a newly issued request.

Inspect frame information

page.on('request', request => {
  if (!request.isNavigationRequest()) return;

  const frame = request.frame();
  console.log({
    url: request.url(),
    method: request.method(),
    frameUrl: frame ? frame.url() : null,
  });
});

The method concerns navigation of the request’s current frame, which may not be the main page frame. The frame() method can return null, including when navigating to error pages, so guard it before reading frame properties.

Do not substitute a heuristic

Resource type, URL shape, or method can be useful metadata, but none is the documented navigation test. A document-like URL or a GET request is not a substitute for isNavigationRequest(). Use url(), method(), and resourceType() to describe a request after checking the navigation predicate.

Options, performance, and reliability

isNavigationRequest() takes no arguments and returns a boolean. It is a classification method on the event’s HTTPRequest; no request interception setup is needed just to inspect it. Interception is a separate feature used when aborting, continuing, or fulfilling requests.

Keep the event callback lightweight if you are observing many resources. Logging every image, script, and stylesheet can produce large output and slow down your own processing. Filter first when you only need navigation requests. If your task needs to establish that navigation completed, wait for the relevant page navigation or lifecycle condition in your flow; the boolean alone is not a completion signal.

Troubleshooting

Symptom	Cause	Fix
request.isNavigationRequest is not a function	The callback value is not the Puppeteer HTTPRequest you expect, or a different API/version is in use.	Attach the listener to page.on('request', request => ...) and inspect the Puppeteer package and matching API reference.
No navigation request appears in the log	The listener may be registered after the navigation, or the page action may not trigger a frame navigation.	Register the listener before page.goto() or before the action being observed. Confirm the action actually navigates a frame.
A request returns false but seems important	Importance is not the method’s criterion; it checks whether the request drives frame navigation.	Use the boolean for navigation classification and inspect URL, method, resource type, or frame separately for other needs.
The request is marked finished despite a 404 or 503	Puppeteer treats HTTP error responses as successful completion at the request lifecycle level.	Inspect the response status separately; use requestfailed for transport or request lifecycle failures.
request.frame() is null	The API allows a null frame, including for navigation to error pages.	Null-check the frame and avoid assuming every request maps to an available frame object.

Or skip the browser setup

If your goal is a screenshot rather than request instrumentation, ScreenshotNeo provides a one-request screenshot API. Its API documentation covers the available options.

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

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its 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.

Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

FAQ

Does isNavigationRequest() tell me whether a page loaded successfully?

No. It classifies the request’s role in frame navigation. Use request lifecycle events and response status for outcome information.

Can I call it without listening for the request event?

You need an HTTPRequest instance to call the method. The page’s request event is the usual way to receive that object.

Which Puppeteer version does the cited reference describe?

The reference consulted displays version 25.12.0. Consult the reference matching your installed package when version differences matter.