How to Stop a Puppeteer Screen Recording

To stop a screen recording created with current Puppeteer, call await recorder.stop() on the ScreenRecording returned by page.record(). If you want a file, pass its path when recording starts, and stop the recorder before closing the browser.

const recorder = await page.record({ path: 'recording.mp4' });
// Perform the actions you want to capture.
await recorder.stop();
await browser.close();

See Puppeteer’s Page.record() reference and ScreenRecording.stop() reference.

1. Stop a recording started with current Puppeteer

page.record() returns a promise for a recorder object. Await it, retain that object, and call its stop() method when capture is finished. Awaiting the stop lets Puppeteer finish the recording before the browser is closed.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.goto('https://example.com');

  const recorder = await page.record({ path: 'recording.mp4' });
  await page.click('body'); // Replace with the interactions to record.

  await recorder.stop();
} finally {
  await browser.close();
}

The recording is an MP4 video stream. The path is supplied when starting the recording, as in the official example; stopping finalizes the recording rather than taking a destination argument.

2. Choose the correct API for your recorder

How recording started	Stop operation	Notes
Current built-in API: page.record()	await recorder.stop()	Returns a ScreenRecording; current docs describe MP4 output.
Older built-in API: page.screencast()	await recorder.stop()	Puppeteer’s next documentation labels this API obsolete and directs users to page.record(). That documentation describes WebM with VP9 at 30 FPS by default and an ffmpeg requirement.
Third-party puppeteer-screen-recorder package	await recorder.stop()	Use the object returned or managed by that package and its own start/stop lifecycle; do not mix it with the built-in Page API.

Check the installed Puppeteer version and the code that creates your recorder. API availability and behavior depend on which entry point and package you use. The legacy and third-party details here come from their respective documentation; consult the version-specific reference before changing an existing recording pipeline.

3. Save the recording when stopping

For the current built-in API, specify path in the options passed to page.record(). Then await stop() and only afterward close the browser:

const recorder = await page.record({ path: 'artifacts/run.mp4' });
// ...record browser actions...
await recorder.stop();
await browser.close();

Create the destination directory before starting if it does not exist. If you need a different format or output behavior, verify support in the documentation for the exact Puppeteer version and recording API in use.

4. Handle errors and cleanup reliably

Put browser cleanup in a finally block so a navigation or interaction error does not leave Chrome running. If recording began successfully, try to stop it before closing the browser:

const browser = await puppeteer.launch();
let recorder;
try {
  const page = await browser.newPage();
  recorder = await page.record({ path: 'recording.mp4' });
  await page.goto('https://example.com');
  // ...interactions...
} finally {
  if (recorder) {
    await recorder.stop();
  }
  await browser.close();
}

If the operation being recorded can throw and stopping can also fail, preserve the original error while still attempting browser cleanup. In production code, handle a stop error separately so it does not silently hide the navigation or interaction failure.

5. Troubleshoot common problems

Symptom	Likely cause	What to do
recorder.stop is not a function	The value is not the recorder returned by the API you think created it, or a different package/version is in use.	Trace the start call, retain its returned recorder, and check the installed Puppeteer or wrapper version and reference.
The output file is missing	No output path was supplied, the path points to a missing directory, or stopping did not complete.	Set path at page.record() startup, ensure its parent directory exists, and await recorder.stop() before browser close.
The recording is incomplete or unusable	The browser was closed before the recorder finished stopping.	Await stop before calling browser.close().
An old snippet uses page.screencast()	It may target the obsolete API documented by Puppeteer’s next reference.	For current code, use page.record() and its returned ScreenRecording when supported by your installed version.
Package examples do not match the built-in API	A third-party wrapper has its own recorder object and lifecycle.	Use that package’s own start and stop methods; do not assume its options match Puppeteer’s built-in API.

6. Performance, reliability, and cost considerations

Screen recording adds video capture and file output to browser automation. Keep the recording interval limited to the actions you need, save to a writable location with adequate space, and stop as soon as capture is complete. The cited Puppeteer API references do not provide a universal performance benchmark or pricing figure; actual resource use depends on the page, browser, environment, and recording duration.

For reliable automation, await navigation and important page state before performing actions, await the stop operation, and close the browser in cleanup. Treat recording as an artifact-producing step: verify that the expected output path is available to your downstream process.

Or skip the browser setup

If your goal is a screenshot rather than a video of browser interactions, ScreenshotNeo is a website screenshot API and MCP server. Its one-call API returns an image or PDF; it does not create a screen recording. The API accepts common screenshot parameter names, which can make switching easier. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

Sign up for 1,000 free screenshots a month, with no card required.

7. Frequently asked questions

How do I stop a Puppeteer screen recording?

Call and await stop() on the recorder returned by the recording API: for current built-in Puppeteer, that is the object returned by await page.record(...).

Does stop() take the file path?

No path is shown in the current official example at stop time. Set the output path when calling page.record().

Can I close the browser immediately after calling stop?

Await recorder.stop() first so recording finalization completes before browser shutdown.

Why doesn’t recorder.stop() exist?

The variable may not hold the recorder object, or it may have been created by another API or wrapper. Identify the start call and match the stop method to that implementation.