<titledata-rh="true">Request interception | Puppeteer</title><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://pptr.dev/guides/request-interception"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="17.0.0"><metadata-rh="true"name="docusaurus_tag"content="docs-default-17.0.0"><metadata-rh="true"name="docsearch:version"content="17.0.0"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-17.0.0"><metadata-rh="true"property="og:title"content="Request interception | Puppeteer"><metadata-rh="true"name="description"content="Once request interception is enabled, every request will stall unless it's continued, responded or aborted."><metadata-rh="true"property="og:description"content="Once request interception is enabled, every request will stall unless it's continued, responded or aborted."><linkdata-rh="true"rel="icon"href="/img/favicon.ico"><linkdata-rh="true"rel="canonical"href="https://pptr.dev/guides/request-interception"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/guides/request-interception"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/guides/request-interception"hreflang="x-default"><linkrel="stylesheet"href="/assets/css/styles.b0ce6a3c.css">
3rd party packages may register their own handlers. It is therefore
important to always check the resolution status using <ahref="#httprequestisinterceptresolutionhandled">request.isInterceptResolutionHandled</a>
before calling <code>abort/continue/respond</code>.</p><p>Importantly, the intercept resolution may get handled by another listener while your handler is awaiting an asynchronous operation. Therefore, the return value of <code>request.isInterceptResolutionHandled</code> is only safe in a synchronous code block. Always execute <code>request.isInterceptResolutionHandled</code> and <code>abort/continue/respond</code><strong>synchronously</strong> together.</p><p>This example demonstrates two synchronous handlers working together:</p><divclass="language-js codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-js codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic">/*</span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic">This first handler will succeed in calling request.continue because the request interception has never been resolved.</span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic">*/</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token method function property-access"style="color:#d73a49">on</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'request'</span><spanclass="token punctuation"style="color:#393A34">,</span><spanclass="token plain"></span><spanclass="token parameter">interceptedRequest</span><spanclass="token plain"></span><spanclass="token arrow operator"style="color:#393A34">=></span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">{</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword control-flow"style="color:#00009f">if</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token plain">interceptedRequest</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token method function property-access"style="color:#d73a49">isInterceptResolutionHandled</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token plain"></span><spanclass="token keyword control-flow"style="color:#00009f">return</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> interceptedRequest</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token keyword control-flow"style="color:#00009f">continue</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">}</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token comment"style="color:#999988;font-style:italic">/*</span><br></span><spanclass="token-line"s
handlers are using Cooperative Intercept Mode, Puppeteer guarantees that all intercept handlers will run and be awaited in order of registration. The interception is resolved to the highest-priority resolution. Here are the rules of Cooperative Intercept Mode:</p><ul><li>All resolutions must supply a numeric <code>priority</code> argument to <code>abort/continue/respond</code>.</li><li>If any resolution does not supply a numeric <code>priority</code>, Legacy Mode is active and Cooperative Intercept Mode is inactive.</li><li>Async handlers finish before intercept resolution is finalized.</li><li>The highest priority interception resolution "wins", i.e. the interception is ultimately aborted/responded/continued according to which resolution was given the highest priority.</li><li>In the event of a tie, <code>abort</code>><code>respond</code>><code>continue</code>.</li></ul><p>For standardization, when specifying a Cooperative Intercept Mode priority use <code>0</code> or <code>DEFAULT_INTERCEPT_RESOLUTION_PRIORITY</code> (exported from <code>HTTPRequest</code>) unless you have a clear reason to use a higher priority. This gracefully prefers <code>respond</code> over <code>continue</code> and <code>abort</code> over <code>respond</code> and allows other handlers to work cooperatively. If you do intentionally want to use a different priority, higher priorities win over lower priorities. Negative priorities are allowed. For example, <code>continue({}, 4)</code> would win over <code>continue({}, -2)</code>.</p><p>To preserve backward compatibility, any handler resolving the intercept without specifying <code>priority</code> (Legacy Mode) causes immediate resolution. For Cooperative Intercept Mode to work, all resolutions must use a <code>priority</code>. In practice, this means you must still test for
<code>request.isInterceptResolutionHandled</code> because a handler beyond your control may have called <code>abort/continue/respond</code> without a
priority (Legacy Mode).</p><p>In this example, Legacy Mode prevails and the request is aborted immediately because at least one handler omits <code>priority</code> when resolving the intercept:</p><divclass="language-ts codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-ts codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic">// Final outcome: immediate abort()</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">setRequestInterception</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token boolean"style="color:#36acaa">true</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">on</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'request'</span><spanclass="token punctuation"style="color:#393A34">,</span><spanclass="token plain"> request </span><spanclass="token operator"style="color:#393A34">=></span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">{</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">if</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token plain">request</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">isInterceptResolutionHandled</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">return</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token comment"style="color:#999988;font-style:italic">// Legacy Mode: interception is aborted immediately.</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> request</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">abort</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'failed'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">}</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain">page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">on</span><spanclass="token punctuation"
your handler means to take no special action, or 'opt out', <code>request.continue()</code> must still be called.</p><p>With the introduction of Cooperative Intercept Mode, two use cases arise for cooperative request continuations:
Unopinionated and Opinionated.</p><p>The first case (common) is that your handler means to opt out of doing anything special the request. It has no opinion on further action and simply intends to continue by default and/or defer to other handlers that might have an opinion. But in case there are no other handlers, we must call <code>request.continue()</code> to ensure that the request doesn't hang.</p><p>We call this an <strong>Unopinionated continuation</strong> because the intent is to continue the request if nobody else has a better idea. Use <code>request.continue({...}, DEFAULT_INTERCEPT_RESOLUTION_PRIORITY)</code> (or <code>0</code>) for this type of continuation.</p><p>The second case (uncommon) is that your handler actually does have an opinion and means to force continuation by overriding a lower-priority <code>abort()</code> or <code>respond()</code> issued elsewhere. We call this an <strong>Opinionated continuation</strong>. In these rare cases where you mean to specify an overriding continuation priority, use a custom priority.</p><p>To summarize, reason through whether your use of <code>request.continue</code> is just meant to be default/bypass behavior vs falling within the intended use case of your handler. Consider using a custom priority for in-scope use cases, and a default priority otherwise. Be aware that your handler may have both Opinionated and Unopinionated cases.</p><h2class="anchor anchorWithStickyNavbar_LWe7"id="upgrading-to-cooperative-intercept-mode-for-package-maintainers">Upgrading to Cooperative Intercept Mode for package maintainers<aclass="hash-link"href="#upgrading-to-cooperative-intercept-mode-for-package-maintainers"title="Direct link to heading"></a></h2><p>If you are package maintainer and your package uses intercept handlers, you can update your intercept handlers to use Cooperative Intercept Mode. Suppose you have the following existing handler:</p><divclass="language-ts codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-ts codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token plain">page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">on</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'request'</span><spanclass="token punctuation"style="color:#393A34">,</span><spanclass="token plain"> interceptedRequest </span><spanclass="token operator"style="color:#393A34">=></span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">{</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">if</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token plain">request</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">isInterceptResolutionHandled</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">return</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">if</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> interceptedRequest</span><spanclass="tokenpunctu
