<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/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="19.2.2"><metadata-rh="true"name="docusaurus_tag"content="docs-default-19.2.2"><metadata-rh="true"name="docsearch:version"content="19.2.2"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-19.2.2"><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/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"><linkdata-rh="true"rel="preconnect"href="https://DVKY664LG7-dsn.algolia.net"crossorigin="anonymous"><linkrel="search"type="application/opensearchdescription+xml"title="Puppeteer"href="/opensearch.xml"><linkrel="stylesheet"href="/assets/css/styles.b357ffad.css">
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"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<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
instead.</p><p>However, we recommend a slightly more robust solution because the above
introduces several subtle issues:</p><ol><li><strong>Backward compatibility.</strong> If any handler still uses a Legacy Mode
resolution (ie, does not specify a priority), that handler will resolve the
interception immediately even if your handler runs first. This could cause
disconcerting behavior for your users because suddenly your handler is not
resolving the interception and a different handler is taking priority when
all the user did was upgrade your package.</li><li><strong>Hard-coded priority.</strong> Your package user has no ability to specify the
default resolution priority for your handlers. This can become important when
the user wishes to manipulate the priorities based on use case. For example,
one user might want your package to take a high priority while another user
might want it to take a low priority.</li></ol><p>To resolve both of these issues, our recommended approach is to export a
<code>setInterceptResolutionConfig()</code> from your package. The user can then call
<code>setInterceptResolutionConfig()</code> to explicitly activate Cooperative Intercept
Mode in your package so they aren't surprised by changes in how the interception
is resolved. They can also optionally specify a custom priority using
<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
to adjust the importance of your package in the resolution chain when
Cooperative Intercept Mode is being used. Your package continues to work as
expected until the user has fully upgraded their code and all third party
packages to use Cooperative Intercept Mode. If any handler or package still uses
