Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Use await page.setContent(html) to replace a Puppeteer page’s document content with an HTML string. Await the promise before inspecting or interacting with the new content; add wait options or a separate readiness wait when the next task depends on a particular load event, element, or application state.
Set a page’s content with page.setContent()
setContent() takes an HTML string, not a URL, and returns a promise that resolves when the operation’s wait condition is met. The current Puppeteer API reference lists this method in version 25.12.0: Page.setContent().
await page.setContent(`<!doctype html>
<html>
<head><title>Example</title></head>
<body><main><h1>Hello</h1></main></body>
</html>`);
const heading = await page.$eval('h1', element => element.textContent);
console.log(heading); // HelloUse a complete document when you need document-level metadata or a predictable document structure. A fragment is also suitable when the page context is sufficient for the task.
Choose when the operation should finish
The optional second argument accepts wait options. The documented default is waitUntil: 'load', with a default timeout of 30,000 milliseconds. If you provide an array of lifecycle events, Puppeteer waits until every event in that array has fired. See the WaitForOptions reference.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
await page.setContent('<main><h1>Rendered markup</h1></main>', {
waitUntil: 'load',
timeout: 30_000,
});- Use
waitUntilto choose the lifecycle event or events that suit the content-setting operation. - Use the per-call
timeoutwhen this particular operation needs a different limit. - Do not assume that reaching a lifecycle event means an application-specific task is ready; wait for that condition separately if necessary.
You can also set a shared navigation timeout. Puppeteer’s Page.setDefaultNavigationTimeout() reference says it applies to page.setContent() as well as the listed navigation methods.
Wait for the element or app state your next step needs
setContent() puts the supplied markup into the page. If subsequent work depends on an element or application state, express that requirement with a separate wait rather than treating the lifecycle wait as proof that the task is complete.
Wait for an element
await page.setContent('<div id="app"></div>');
await page.waitForSelector('#app');waitForSelector() can also wait for visibility or hidden state and supports timeout and abort-signal options. Consult the Page.waitForSelector() reference for its options.
Rank #2
Wait for a condition
When readiness is represented by a state rather than a particular selector, use waitForFunction():
await page.waitForFunction(() => window.appReady === true);The function runs in the browser context and Puppeteer waits until it returns a truthy value. It can also receive arguments from Node.js; see the Page.waitForFunction() reference.
Prefer locators for interactions
For element interactions, Puppeteer’s guide recommends locators, which automatically wait for the element to be present and in the right state. That interaction readiness is distinct from setting the document’s markup; see the page interactions guide.
Set content inside a particular frame
Use frame.setContent() when the target is an iframe or another specific frame, rather than replacing the main page’s content. The method takes an HTML string and optional options; the official reference displays Puppeteer version 25.10.0: Frame.setContent().
const frame = page.frames().find(candidate => candidate.name() === 'preview');
if (!frame) throw new Error('Preview frame not found');
await frame.setContent('<main><p>Frame content</p></main>');Check that the frame lookup succeeds before calling the method. If the frame is identified differently in your page, use the appropriate frame lookup for that page.
Troubleshoot common setContent() problems
The call times out
The operation did not satisfy its configured wait condition before the timeout. Check the chosen waitUntil event or events and whether they are appropriate for your content. Set a suitable per-call timeout or shared navigation timeout if the task genuinely needs more time. If the real requirement is an element or application state, use a separate waitForSelector() or waitForFunction() wait instead of extending the lifecycle wait without a reason.
The next step runs before the app is ready
Await setContent(), then wait for the concrete condition needed by the next step. A lifecycle event and an application-specific readiness condition answer different questions.
Content appears in the wrong document
page.setContent() sets the page content. If the target is an iframe, find that frame and call its setContent() method.
Untrusted HTML is being inserted
The API assigns the supplied string as page markup; the method reference does not promise to sanitize it or prevent scripts and external resources from running. Treat untrusted markup as untrusted browser content and apply the security controls appropriate to your application.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesBest Value
- Used Book in Good Condition
Or skip the browser setup
If your goal is to capture a website rather than populate a Puppeteer page with custom HTML, ScreenshotNeo offers a one-request screenshot API and an MCP server:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for API options. Before capture, it accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response identifies the page verdict and billing status in headers. Its MCP tools let AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
