Enable request interception before navigation, listen for each request event, and call request.continue() on requests you want the browser to send. Every intercepted request needs a resolution—continue, respond, abort, or complete through the browser cache—or it can stall page loading.
Continue requests with the basic interception pattern
Use this sequence: enable interception, register the handler, then navigate. The Puppeteer guide demonstrates this enable-listen-continue flow. The documentation consulted is labeled Puppeteer 25.12.0; check the documentation for your installed release if you target an older version.
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;
// Continue requests that need no special handling.
request.continue();
});
await page.goto('https://example.com');
} finally {
await browser.close();
}Interception must be enabled before using the request-continuation API. See Page.setRequestInterception() and HTTPRequest.continue().
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Why pass-through requests still need handling
Once interception is active, a request does not simply proceed because your handler has no changes to make. Explicitly continue it. As the Puppeteer Request Interception guide puts it, “Puppeteer requires request.continue() to be called explicitly or the request will hang.”
#1 Best Overall
Avoid resolving a request twice
Another request listener or package may already have continued, responded to, or aborted the request. Resolving it again can raise Request is already handled!. Check isInterceptResolutionHandled() immediately before acting.
If your handler awaits asynchronous work, check again afterward. A check made before an await can become stale while the handler is paused; keep the final check and resolution adjacent and synchronous:
Rank #2
page.on('request', async request => {
if (request.isInterceptResolutionHandled()) return;
await decideWhatToDo(request);
// Another handler may have resolved it during the await.
if (request.isInterceptResolutionHandled()) return;
request.continue();
});Use this guard when other listeners may be installed. For a handler with no asynchronous decision-making, the simple synchronous pattern avoids an unnecessary race window.
Continue with request overrides
request.continue(overrides?, priority?) accepts optional overrides and an optional priority, and returns a Promise<void>. The documented header example copies existing headers, adds one, and removes another by assigning undefined:
page.on('request', request => {
if (request.isInterceptResolutionHandled()) return;
const headers = {
...request.headers(),
foo: 'bar',
origin: undefined, // remove the origin header
};
request.continue({ headers });
});Use the installed release’s ContinueRequestOverrides type to confirm which request fields are supported; the available overrides are defined by Puppeteer’s API and can vary by version. Do not assume every property of a request can be changed.
Coordinate multiple handlers with priorities
Without a priority, a resolution takes effect immediately using legacy behavior. Cooperative Intercept Mode applies only when every resolution supplies a numeric priority; Puppeteer then waits for asynchronous handlers and selects the highest priority. For equal priorities, the order is abort, then respond, then continue. A single legacy resolution can still act immediately, so keep the handled-state check when other listeners may exist.
Rank #4
If a handler has no special preference and should allow another handler to make a deliberate decision, the guide recommends an unopinionated continuation at priority 0 or DEFAULT_INTERCEPT_RESOLUTION_PRIORITY. A higher custom priority is for a handler that intentionally wants to override another resolution.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →import puppeteer, {
DEFAULT_INTERCEPT_RESOLUTION_PRIORITY,
} from 'puppeteer';
page.on('request', request => {
if (request.isInterceptResolutionHandled()) return;
request.continue(
request.continueRequestOverrides(),
DEFAULT_INTERCEPT_RESOLUTION_PRIORITY,
);
});Confirm that the constant is exported by your installed Puppeteer release before using this version-specific import. For exact semantics, see the network interception guide and the continue API reference.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot stalled or failed interception
| Symptom | Likely cause | What to check or change |
|---|---|---|
| Navigation or page loading stalls | An intercepted request never received a resolution. | Ensure every request your handler receives is continued, responded to, or aborted as appropriate. A pass-through request still needs continue(). |
Request is already handled! |
A different listener or package resolved the same request first, or it did so during an asynchronous wait. | Check isInterceptResolutionHandled() immediately before resolving and repeat the check after any await. |
| Continuation fails because interception is disabled | setRequestInterception(true) was not called before using the continuation API. |
Enable interception on the page before navigation and before calling request.continue(). |
| Handlers produce an unexpected result | At least one handler may be resolving without a priority, invoking legacy behavior instead of cooperative finalization. | Review every handler that can resolve the request. Cooperative resolution requires numeric priorities for all resolutions. |
Or skip the browser setup
If your goal is to get a clean screenshot rather than control individual browser requests, ScreenshotNeo provides a screenshot API and MCP server. A single GET request can return a PNG, JPEG, WebP, or PDF; the API is not a replacement for Puppeteer’s request-interception logic.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo and get 1,000 free screenshots a month with no card.
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.
