Use await page.goto('https://example.com') to navigate a Puppeteer page to a URL. Include the URL scheme, then choose a navigation wait condition that fits what you will do next; the default is to wait for the page’s load event.
Navigate with page.goto()
This complete JavaScript example launches Puppeteer, opens a page, navigates to a URL, and prints the main resource’s HTTP status when a response is available:
As an Amazon Associate I earn from qualifying purchases.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
const response = await page.goto('https://example.com');
console.log('HTTP status:', response?.status());
} finally {
await browser.close();
}The example uses ES modules and top-level await. Puppeteer’s getting-started guide also demonstrates importing either puppeteer or puppeteer-core; choose the package appropriate to your project and browser setup. See the official getting-started guide.
Free tools Windows power users keep installed
One-click scans. No signup required.
page.goto() returns a promise for the main resource response. It can resolve to null for cases such as navigating to about:blank or changing only the hash on the same URL. An HTTP error status does not necessarily make navigation throw: inspect the returned response’s status when the result matters. Puppeteer’s documentation specifically notes that in headless shell, statuses such as 404 and 500 do not cause goto to throw. See the Page.goto API reference.
#1 Best Overall
Choose when navigation should count as complete
goto accepts waitUntil to define the browser lifecycle event or events Puppeteer waits for. In the documentation version 25.12.0, the default is load; the default navigation timeout is 30,000 milliseconds. You can supply one event or an array, in which case all listed events must fire before the wait succeeds. These values are API defaults, not a guarantee that every page is ready for your next operation.
await page.goto('https://example.com', {
waitUntil: 'domcontentloaded',
timeout: 45_000,
});This illustrative call waits for domcontentloaded and allows 45 seconds for the configured completion condition. Pick a condition based on what follows: a lifecycle event may be enough for one task, while an application-specific element may be a better signal for another. The API also documents timeout: 0 as disabling the timeout; use it only when you deliberately want navigation to have no time limit. Check the WaitForOptions reference for the version your project uses.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Set a navigation timeout
Use the timeout option in a goto call to tune that navigation. To change the default limit for a page’s navigation operations, call page.setDefaultNavigationTimeout(milliseconds):
page.setDefaultNavigationTimeout(45_000);
await page.goto('https://example.com');The default navigation timeout applies to goto, waitForNavigation, reload, and related methods. Prefer a per-call timeout when only one navigation needs different handling; use the page-level setting when the same limit should govern navigation calls on that page. See the setDefaultNavigationTimeout API reference.
Rank #3
Wait for navigation caused by a click
When a link or button triggers a new navigation, register the navigation wait before clicking. Use Promise.all so the wait is already active when the click occurs:
const [response] = await Promise.all([
page.waitForNavigation(),
page.locator('a.next').click(),
]);
console.log('HTTP status:', response?.status());Starting the click first and waiting afterward risks missing a fast navigation. waitForNavigation() returns the main resource response for ordinary navigation, but may return null for a different anchor or a History API navigation. History API URL changes count as navigation. See the waitForNavigation API reference and Puppeteer’s documented click-and-wait pattern.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Wait for the page content your task needs
A navigation lifecycle event tells you something about loading; it does not prove that a specific application element is ready. For interaction, Puppeteer recommends locators, which wait for element presence and action preconditions such as visibility, enabled state, and stable layout. After navigation, act on the locator for the content or control your task actually needs rather than assuming that the URL change alone is sufficient. See the page interactions guide.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Puppeteer’s official screenshot and PDF examples use waitUntil: 'networkidle2'. Treat that as an example workflow choice, not a universally best setting; choose the condition according to the target page and the operation that follows. See the screenshot guide and PDF generation guide.
Troubleshoot navigation failures
- Invalid URL: Check that the address is valid and includes its scheme, such as
https://. - Navigation timeout: Puppeteer did not observe the selected completion condition before the configured limit. Check whether the condition matches the task before increasing the timeout; use a per-call or page-level timeout as appropriate.
- SSL error or unreachable server: Verify the target address and whether the server is reachable from the machine running the browser.
- Main resource fails to load: Check the target’s response and browser/network conditions. Navigation can fail when the main resource does not load.
- Navigation appears successful but the page is not usable: Wait for the relevant application element with a locator; lifecycle completion and application readiness are different conditions.
- Navigation returns no response: A
nullresponse can be expected for same-document cases such as a hash-only change or History API navigation. Do not treatnullalone as proof of a failed page load. - HTTP 404 or 500: Read the response status. In headless shell, a valid HTTP status such as 404 or 500 does not make
gotothrow.
Puppeteer lists invalid target URLs, SSL errors, timeouts, unreachable servers, and failures loading the main resource among navigation failure causes. See the HTTPError API reference.
Or skip the browser setup
If you only need a URL captured as an image or PDF, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request can return PNG, JPEG, WebP, or PDF. For an image capture, save the response body as a file:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo documentation for API options. Cookie banners are accepted and removed before capture, along with supported consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers indicate the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently Asked Questions
Which Puppeteer documentation version do these defaults refer to?
The documented navigation option defaults cited here are from Puppeteer documentation version 25.12.0; check the API reference for the version used by your project.
Can `page.goto()` return `null` without indicating an ordinary load failure?
Yes. Documented same-document cases include navigating to `about:blank` and changing only the URL hash; `waitForNavigation()` can also return `null` for anchor or History API navigation.
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.
Recommended Free Tools
