Skip to content

v25.17.0 and v25.17.1

Combined notes for Puppeteer Sharp 25.17.0 and 25.17.1, both released on November 13, 2026. The public API tracks Puppeteer 25.17.0. Target frameworks are unchanged: netstandard2.0, net8.0, and net10.0.

Install 25.17.1. NuGet does not list 25.17.0. On November 16, 2026, PuppeteerSharp 25.17.0 reported that the version was not found and showed 25.17.1 instead. The package history jumps from 25.15.0 to 25.17.1. There is no v25.16.0 tag.

Terminal window
dotnet add package PuppeteerSharp --version 25.17.1

The browsers downloaded by default move from Chrome 155.0.8059.84 to Chrome 157.0.8103.78, and from Firefox 158.0 (stable_158.0) to Firefox 160.0 (stable_160.0). Puppeteer 25.17.0 itself rolled Chrome to 157.0.8103.38. This package includes the later roll to 157.0.8103.78 (#3747), after 156.0.8078.47 (#3635) and 157.0.8103.50 (#3665). Firefox 158.0.1 landed in between (#3652) and was then rolled to 160.0 (#3715).

The docs moved from DocFX on GitHub Pages to this Starlight site (#3655, #3656, #3657). Guides start at Docs.

Stream a response, and read its encoded size

Section titled “Stream a response, and read its encoded size”

IResponse.StreamAsync returns a Stream of the body, with chunks delivered as they arrive (#3666). Call it from the Response event, while the body is still loading. If loading has already finished, the stream is a buffer of the whole body. Read until the stream ends. Each read still returns at most the buffer you pass. A redirect also raises Response, and StreamAsync then throws PuppeteerException (Response body is unavailable for redirect responses). A failed load throws PuppeteerException from a later read. The handler is not awaited, so catch those failures inside it.

StreamAsync is a CDP method. On WebDriver BiDi it returns a faulted task with NotSupportedException and the message Response.StreamAsync is not supported in WebDriver BiDi. Use BufferAsync or TextAsync on BiDi.

EncodedDataLength is the number of bytes received for the request over the network (#3670). During the Response event it only covers bytes received up to the response headers. Read it in a RequestFinished handler, or after BufferAsync, for the full encoded size (headers plus the compressed body). A request that fails after the response arrives does not update the value. When the browser reports no size, including data: and file: URLs, the value stays 0. On BiDi the property is the bytes received, and a negative report is stored as 0.

page.Response += async (_, e) =>
{
try
{
using var body = await e.Response.StreamAsync();
var buffer = new byte[8192];
int read;
while ((read = await body.ReadAsync(buffer, 0, buffer.Length)) > 0)
{
// Process `read` bytes from `buffer`.
}
}
catch (PuppeteerException)
{
// Redirects and failed loads have no readable body.
}
};
page.RequestFinished += (_, e) =>
{
var encodedBytes = e.Request.Response?.EncodedDataLength;
};

IRequest.ContentAsync returns the unmodified POST bytes, or null when the request has no body or the browser cannot return it (#3637). PostData is the string already known to the client. FetchPostDataAsync decodes ContentAsync as UTF-8.

page.Request += async (_, e) =>
{
if (!e.Request.HasPostData)
{
return;
}
byte[] bytes = await e.Request.ContentAsync();
};

Request, response, and console events on the browser

Section titled “Request, response, and console events on the browser”

IBrowser and IBrowserContext raise the same network and console events as a page:

  • Request, RequestFinished, RequestFailed, and RequestServedFromCache (#3667, #3672)
  • Response (#3672)
  • Console (#3673), including console messages from dedicated workers (#3674)

Request handlers receive RequestEventArgs. Response handlers receive ResponseCreatedEventArgs. Console handlers receive ConsoleEventArgs. IRequest now exposes Page and Worker (#3675). ConsoleMessage exposes Page, Frame, and Worker (#3682).

browser.Request += (_, e) =>
Console.WriteLine($"{e.Request.Method} {e.Request.Url}");
browser.Response += (_, e) =>
Console.WriteLine($"{(int)e.Response.Status} {e.Response.Url}");
browser.Console += (_, e) =>
Console.WriteLine(e.Message.Text);
IBrowserContext context = browser.DefaultContext;
context.Request += (_, e) =>
Console.WriteLine(e.Request.Url);

IRequest.Method is an HttpMethod. IResponse.Status is an HttpStatusCode.

IPage.ExceptionThrown and WebWorker.ExceptionThrown report an uncaught exception as a RemoteException (#3744). 25.17.0 implements this for CDP. The event args type is RemoteExceptionEventArgs, and the exception is e.Exception.

Text is the browser’s rendering of the thrown value, for example Error: boom, without the stack. Name is Error, TypeError, SyntaxError, AbortError, or an empty string when the thrown value is not an error. StackTrace is the call frames, innermost first, each as a ConsoleMessageLocation. Location is the first frame, or the top-level coordinates for a syntax error. Handle is the live remote value when CDP can expose one.

The handle is disposed as soon as the event has been dispatched, and every handler shares that same handle. Call Move() synchronously inside the handler to keep it, then dispose it.

page.ExceptionThrown += (_, e) =>
{
RemoteException exception = e.Exception;
Console.WriteLine($"{exception.Name}: {exception.Text}");
IJSHandle handle = exception.Handle?.Move();
handle?.Dispose();
};

PageError is still raised. ExceptionThrown is the event to use for the structured exception.

Extra arguments for Locator.Filter and Locator.Map

Section titled “Extra arguments for Locator.Filter and Locator.Map”

Locator.Filter and Locator.Map take a JavaScript function and then extra arguments (#3671). The element is the function’s first parameter. Serializable values and handles in args are forwarded after it. The predicate retries until it returns true. Map transforms the element; WaitAsync<T>() reads the mapped value.

IJSHandle expected = await page.EvaluateExpressionHandleAsync("'true'");
await page.Locator("div")
.Filter(
"(element, attr, value) => element.getAttribute(attr) === value",
"clickable",
expected)
.HoverAsync();
string label = await page.Locator("button")
.Map("(element, name) => element.getAttribute(name)", "aria-label")
.WaitAsync<string>();

LaunchOptions and ConnectOptions accept a DownloadBehavior (#3679). Policy is a DownloadPolicy: Deny, Allow, AllowAndName, or Default. DownloadPath is required for Allow and AllowAndName. AllowAndName names every file from its download GUID. On WebDriver BiDi, AllowAndName throws NotSupportedException (allowAndName is not supported in WebDriver BiDi). Use Allow on BiDi.

await using IBrowser browser = await Puppeteer.LaunchAsync(new LaunchOptions
{
DownloadBehavior = new DownloadBehavior
{
Policy = DownloadPolicy.Allow,
DownloadPath = "/tmp/downloads",
},
});

Puppeteer.ConnectAsync takes the same object on ConnectOptions.

Screen recording without an enumeration buffer

Section titled “Screen recording without an enumeration buffer”

RecordOptions.BufferForEnumeration controls whether recording chunks are kept for await foreach (#3662). The default, null or true, buffers them. Set it to false when the recording only goes to Path or to a pipe, so an unread queue does not retain the video. GetAsyncEnumerator then throws InvalidOperationException. RecordAsync writes an MP4 stream. The obsolete ScreencastAsync is the WebM recorder.

await using ScreenRecording recording = await page.RecordAsync(new RecordOptions
{
Path = "session.mp4",
BufferForEnumeration = false,
});
await page.GoToAsync("https://example.com");
await recording.StopAsync();

DomContentLoaded and NavigationStart metrics

Section titled “DomContentLoaded and NavigationStart metrics”

Page.MetricsAsync returns a Dictionary<string, decimal> that now includes DomContentLoaded and NavigationStart (#3669). Both names are listed on Page.SupportedMetrics. The values are the Chrome performance metrics of those names.

Dictionary<string, decimal> metrics = await page.MetricsAsync();
decimal domContentLoaded = metrics["DomContentLoaded"];
decimal navigationStart = metrics["NavigationStart"];

FrameNavigatedSameDocument and FrameNavigatedNewDocument

Section titled “FrameNavigatedSameDocument and FrameNavigatedNewDocument”

IPage raises FrameNavigatedSameDocument and FrameNavigatedNewDocument after FrameNavigated (#3749). Both are EventHandler<FrameEventArgs>. Same-document navigation is a fragment change or a History API update. New-document navigation loads a new document. FrameEventArgs.Frame is the frame. FrameNavigated still uses FrameNavigatedEventArgs.

page.FrameNavigatedSameDocument += (_, e) =>
Console.WriteLine($"Same document: {e.Frame.Url}");
page.FrameNavigatedNewDocument += (_, e) =>
Console.WriteLine($"New document: {e.Frame.Url}");

ExceptionThrown is also raised for WebDriver BiDi (#3748). BiDi does not expose the exception name or a remote object, so RemoteException.Name is an empty string and RemoteException.Handle is null. Text and StackTrace still come from the JavaScript log entry. Do not call Move() on a BiDi exception’s handle.

An already cancelled token is honored immediately. The call throws OperationCanceledException and does not perform the operation.

WaitForFunctionAsync, GoToAsync, GoBackAsync, GoForwardAsync, ReloadAsync, and WaitForNavigationAsync check the token before they start (#3763). SetContentAsync does the same and leaves the existing HTML in place (#3765).

Pass the token on WaitForFunctionOptions, NavigationOptions, or ReloadOptions. For SetContentAsync, use SetContentOptions. The NavigationOptions overload of SetContentAsync is obsolete.

using var cts = new CancellationTokenSource();
cts.Cancel();
await page.WaitForFunctionAsync(
"() => false",
new WaitForFunctionOptions { CancellationToken = cts.Token });
await page.GoToAsync(
"https://example.com",
new NavigationOptions { CancellationToken = cts.Token });
await page.SetContentAsync(
"<p>Hello</p>",
new SetContentOptions { CancellationToken = cts.Token });

Package publish uses NuGet Trusted Publishing (#3752). The GitHub Actions workflow requests an OIDC token (id-token: write), logs in to nuget.org, and pushes with the short-lived API key from that login. The workflow no longer reads a stored NUGET_API_KEY secret.

A header name or value that contains a carriage return or a line feed throws PuppeteerException. The message starts with Invalid header: CRLF characters are not allowed in header names or values.

SetExtraHttpHeadersAsync validates extra headers (#3683). ContinueAsync validates header overrides on both CDP and WebDriver BiDi (#3728).

--disable-field-trial-config is no longer one of the default Chrome arguments (#3720). Add --disable-field-trial-config to LaunchOptions.Args when a launch still needs it.

Locator.FillAsync does not change a read-only textarea, or a read-only input whose type is text, search, url, tel, email, password, number, date, month, week, time, or datetime-local (#3646). It also refuses a non-empty value that the input type does not accept: a probe input of that type ends up empty, which covers values such as abc in a number input or noon in a time input. A select whose options do not contain the value is refused the same way.

The page function throws Element is read-only. or Element did not accept the value. The locator retries that failure, so the call ends in TimeoutException and the previous value stays. Read-only color and range inputs are still filled. A field that becomes writable while FillAsync is retrying can still receive the value.

DeleteMatchingCookiesAsync honors domain, path, URL, and partition

Section titled “DeleteMatchingCookiesAsync honors domain, path, URL, and partition”

The method is DeleteMatchingCookiesAsync on IBrowser and IBrowserContext (#3645). Each DeleteCookiesRequest matches Name, and also honors Domain, Path, Url, and PartitionKey when they are set.

Domain and Path must equal the cookie’s domain and path. An absolute Url matches only when its host equals the cookie domain and its absolute path equals the cookie path. PartitionKey matches SourceOrigin, and matches HasCrossSiteAncestor when the filter sets that flag. A filter with a partition key does not delete a cookie that has no partition key.

await context.DeleteMatchingCookiesAsync(new DeleteCookiesRequest
{
Name = "session",
Domain = "example.com",
Path = "/",
});

Paper width, height, and margins convert with the CSS absolute-length ratios, on CDP and on WebDriver BiDi (#3647):

Unit Pixels
px 1
in 96
cm 96 / 2.54
mm 96 / 25.4
pt 96 / 72
pc 16

pt and pc are new. Centimeters and millimeters previously used the rounded factors 37.8 and 3.78.

Accessibility element handles after navigation

Section titled “Accessibility element handles after navigation”

SerializedAXNode.ElementHandleAsync returns null after a navigation when the frame’s loader id no longer matches the snapshot (#3650). The stored backend node id can belong to a different node in the new document, so the method returns null instead of adopting that node.

Made with love by Dario Kondratiuk