<titledata-rh="true">Request Interception | Puppeteer</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://pptr.dev/next/guides/request-interception"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docsearch:counter"content="3"><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"><metadata-rh="true"property="og:description"content="Once request interception is enabled, every request will stall unless it's"><linkdata-rh="true"rel="icon"href="/img/favicon.ico"><linkdata-rh="true"rel="canonical"href="https://pptr.dev/next/guides/request-interception"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/request-interception"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/request-interception"hreflang="x-default"><linkdata-rh="true"rel="preconnect"href="https://DVKY664LG7-dsn.algolia.net"crossorigin="anonymous"><linkrel="search"type="application/opensearchdescription+xml"title="Puppeteer"href="/opensearch.xml">
<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"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic">This second handler will return before calling request.abort because request.continue was already</span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic">called by the first handler.</span><br></span><spanclass="toke
synchronously before using <code>abort/continue/respond</code>.</p><p>Here is the example above rewritten using <code>request.interceptResolutionState</code></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 comment"style="color:#999988;font-style:italic">// The interception has not been handled yet. Control will pass through this guard.</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">const</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">{</span><spanclass="token plain">action</span><spanclass="token punctuation"style="color:#393A34">}</span><spanclass="token plain"></span><spanclass="token operator"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">interceptResolutionState</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 keyword control-flow"style="color:#00009f">if</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token plain">action </span><spanclass="token operator"style="color:#393A34">===</span><spanclass="token plain"></span><spanclass="token maybe-class-name">InterceptResolutionAction</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token property-access maybe-class-name">AlreadyHandled</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"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">// It is not strictly necessary to retu
optional <code>priority</code> to work in Cooperative Intercept Mode. When all 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
will hang. Even if 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<ahref="#upgrading-to-cooperative-intercept-mode-for-package-maintainers"class="hash-link"aria-label="Direct link to Upgrading to Cooperative Intercept Mode for package maintainers"title="Direct link to Upgrading to Cooperative Intercept Mode for package maintainers"></a></h2><p>If you are package maintainer and your package uses intercept handlers, you can
<code>setInterceptResolutionConfig(priority)</code> that works for their use case:</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">// Defaults to undefined which preserves Legacy Mode behavior</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">let</span><spanclass="token plain"> _priority </span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">undefined</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">// Export a module configuration function</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">export</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">const</span><spanclass="token plain"></span><spanclass="token function-variable function"style="color:#d73a49">setInterceptResolutionConfig</span><spanclass="token plain"></span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token plain">priority </span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain"></span><spanclass="token number"style="color:#36acaa">0</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token plain"></span><spanclass="token operator"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 plain">_priority </span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain"> priority</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"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic"> * Note that this handler uses `DEFAULT_INTERCEPT_RESOLUTION_PRIORITY` to "pass" on this request. It is important to use</span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic"> * the default priority when your handler has no opinion on the request and the intent is to continue() by default.</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 function"style="color:#d73a49">on</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e
use a config pattern like this:</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 keyword"style="color:#00009f">interface</span><spanclass="token plain"></span><spanclass="token class-name">InterceptResolutionConfig</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"> abortPriority</span><spanclass="token operator"style="color:#393A34">?</span><spanclass="token operator"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token builtin">number</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> continuePriority</span><spanclass="token operator"style="color:#393A34">?</span><spanclass="token operator"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token builtin">number</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 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">// This approach supports multiple priorities based on situational</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token comment"style="color:#999988;font-style:italic">// differences. You could, for example, create a config that</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token comment"style="color:#999988;font-style:italic">// allowed separate priorities for PNG vs JPG.</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">const</span><spanclass="token plain"></span><spanclass="token constant"style="color:#36acaa">DEFAULT_CONFIG</span><spanclass="token operator"style="color:#393A34">:</span><spanclass="token plain"> InterceptResolutionConfig </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"> abortPriority</span><spanclass="token operator"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">undefined</span><spanclass="token punctuation"style="color:#393A34">,</span><spanclass="token plain"></span><spanclass="token comment"style="color:#999988;font-style:italic">// Default to Legacy Mode</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> continuePriority</span><spanclass="token operator"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">undefined</span><spanclass="token punctuation"style="color:#393A34">,</span><spanclass="token plain"></span><spanclass="token comment"style="color:#999988;font-style:italic">// Default to Legacy Mode</span><spanclass="token plain"></span><br></span><spanclas
