To intercept network requests in Puppeteer, enable interception with await page.setRequestInterception(true), then handle each request event by calling continue(), abort(), or respond(). Every intercepted request must be resolved; otherwise, it stalls and can prevent the page from loading.
Enable interception before navigating
This example blocks requests whose URLs end in .png or .jpg and lets other requests proceed. Those suffix checks are only a simple illustration, not a reliable way to identify every image request.
As an Amazon Associate I earn from qualifying purchases.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.setRequestInterception(true);
page.on('request', request => {
if (request.isInterceptResolutionHandled()) return;
if (request.url().endsWith('.png') || request.url().endsWith('.jpg')) {
request.abort();
} else {
request.continue();
}
});
await page.goto('https://example.com');
} finally {
await browser.close();
}Install Puppeteer in your project before running the example. Register the listener before page.goto() so it can handle navigation and page-resource requests from the start. Once interception is on, requests stall until the handler resolves them, unless the browser cache completes them.
Choose what to do with each request
| Method | Effect | Use it when |
|---|---|---|
continue() |
Sends the request onward, optionally with overrides. | The page should get the original resource, possibly with changed request data. |
abort() |
Stops the request. | The page should not fetch that resource. |
respond() |
Fulfills the request with a response you supply. | You want to mock a response instead of contacting the server. |
Continue, optionally changing headers
Pass overrides to continue(). For example, copy the existing headers, change one, and set another to undefined to remove it:
#1 Best Overall
page.on('request', request => {
if (request.isInterceptResolutionHandled()) return;
const headers = {
...request.headers(),
'x-debug-mode': 'true',
'x-remove-this-header': undefined,
};
request.continue({ headers });
});Interception must be enabled before this handler can control requests. Use the header names and values your target application expects.
Return a mock response
Use respond() when the page should receive data generated by the script rather than a network response:
page.on('request', request => {
if (request.isInterceptResolutionHandled()) return;
request.respond({
status: 404,
contentType: 'text/plain',
body: 'Not found',
});
});This example responds to every intercepted request; in an application, match only the URL or request type you intend to mock and continue the rest. Puppeteer documents respond() for a data: URL as a no-op, so do not rely on it to replace such a request.
Free tools Windows power users keep installed
One-click scans. No signup required.
Abort selectively
For selective blocking, test an application-specific condition and continue every request that does not match. A suffix check is easy to demonstrate, but URLs do not always identify a resource by file extension; use a criterion appropriate to your traffic.
Handle multiple listeners and asynchronous checks safely
A dependency or another event listener may try to resolve the same request. Check request.isInterceptResolutionHandled() before acting. If the handler awaits work, check again immediately before resolving: another handler could have acted during the wait.
page.on('request', async request => {
if (request.isInterceptResolutionHandled()) return;
const shouldBlock = await decideWhetherToBlock(request.url());
// Another listener may have resolved it while this handler awaited.
if (request.isInterceptResolutionHandled()) return;
if (shouldBlock) {
request.abort();
} else {
request.continue();
}
});Keep the final handled-state check and the call to abort(), continue(), or respond() together without an intervening await.
Rank #3
Cooperative interception priorities
Puppeteer supports cooperative resolution when every handler resolving a request supplies a numeric priority. Handlers run and are awaited; the highest priority wins. If priorities tie, resolution favors abort over respond over continue. If even one handler omits a priority, legacy immediate resolution applies, so a library should not assume other listeners are participating cooperatively.
Log traffic without intercepting it
If you only need to observe requests, use Puppeteer’s default network events rather than enabling interception:
page.on('request', request => console.log('Request:', request.url()));
page.on('response', response => console.log('Response:', response.status(), response.url()));Request and response events are emitted by default. Interception is for controlling traffic, and adds the responsibility to resolve each intercepted request.
Distinguish HTTP errors from failed requests
Puppeteer emits request, requestfinished, and requestfailed events. A response with HTTP status 404 or 503 is still a completed HTTP response and is associated with requestfinished; check the response status when you need to identify HTTP error codes. Use requestfailed for requests that fail before completing in that lifecycle.
Connection-level URL restrictions are a separate option
Puppeteer also documents URL-pattern allowlist and blocklist options in ConnectOptions. The documentation says this feature is currently supported only for Chrome and cautions that it is not a complete network sandbox. Treat it as a connection-level restriction, not as a replacement for page-level interception when you need to continue, modify, mock, or selectively abort individual requests. See the ConnectOptions reference.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Or skip the browser setup
If your goal is to capture a website screenshot rather than control arbitrary browser traffic, ScreenshotNeo provides a screenshot API and MCP server. A single GET request returns an image or PDF. See the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses indicate the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan to try it without a card.
Troubleshooting
The page hangs or navigation times out
Check that every intercepted request reaches a resolution call. Include a default path that continues requests you do not intend to block or mock, and ensure no conditional branch exits without resolving the request.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchA request is already handled
Another listener, possibly installed by a dependency, may have resolved it. Check isInterceptResolutionHandled() before acting and again after any asynchronous work.
A mocked request still reaches the server
Confirm that interception was enabled before the request began and that the matching branch calls respond() rather than continue(). A data: URL is a documented exception: respond() is a no-op for it.
An HTTP error is not reported as a failed request
A completed 404 or 503 response is not the same as a request that failed before completion. Listen for responses and inspect response.status() to detect HTTP error status codes.
Version and documentation
The Puppeteer guide and API references cited here identify version 25.12.0; the documentation was accessed on October 3, 2026. These are living docs, so check the current reference if behavior or supported browser options matter to your deployment: network logging guide, Page.setRequestInterception(), HTTPRequest.continue(), and HTTPRequest.respond().
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
