The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Short answer: Puppeteer does not publish a maximum URL length for page.goto(). The practical ceiling comes from the Chromium browser that Puppeteer controls: Chromium documents a 2 MB maximum URL length. That is a browser-side limit, not an end-to-end promise. Your web server, reverse proxy, gateway, redirect chain or URL validation can reject a much shorter request.
If a very long navigation fails, verify the URL and the exact error first. Do not assume that every timeout, HTTP error or blank page is a character-count failure.
What Puppeteer itself guarantees
The page.goto() API documentation defines the method as navigation to the supplied URL and says the value should include a scheme such as https://. It does not specify a maximum in characters or bytes.
Therefore, there is no Puppeteer option such as maxUrlLength, no documented Puppeteer-specific tier, and no API guarantee that a URL below a particular size will succeed. Puppeteer passes navigation to Chromium; the browser implementation determines what happens after that.
Recommended Free Tools
#1 Best Overall
Where the 2 MB figure comes from
Chromium’s URL display guidelines state that the web platform generally has no URL-length limit, but Chrome limits URLs to a maximum of 2 MB for practical reasons and to reduce denial-of-service risk in inter-process communication. This is the best-supported number for Puppeteer running Chrome or Chromium.
The number is a browser implementation ceiling, not a promise about every navigation path. A Chromium code change dated April 12, 2024 gives a more specific warning: when a valid GURL longer than 2 MB is passed between processes, it can be replaced with an invalid URL. That describes a particular inter-process code path; it does not mean every oversized URL fails identically.
| Layer | What is documented | How to interpret it |
|---|---|---|
Puppeteer page.goto() |
No byte or character maximum in the API reference | There is no Puppeteer-level limit you can configure or rely on |
| Chrome/Chromium navigation | 2 MB maximum for practical and inter-process safety reasons | Use it as a browser-side ceiling, not an end-to-end guarantee |
| Chromium GURL transfer | URLs over 2 MB may become invalid when passed between processes | An implementation warning for a specific code path |
| Origin server and intermediaries | Limits vary by server, proxy and gateway; no universal cross-vendor number is established here | A shorter URL can still be rejected before the page loads |
Do not confuse navigation length with address-bar display
Chromium separately documents address-bar display thresholds: 32 kB on most platforms and 1 kB on VR platforms. Those values describe how much of a URL the omnibox displays, not how long a URL Chrome can navigate to. A clipped or elided address-bar string is not evidence that page.goto() reached a navigation limit.
For automation, measure the URL string sent to page.goto() and inspect the resulting request. Do not use what a headed browser happens to show in its address bar as your test.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Why a long page.goto() call can fail below 2 MB
The target is not a valid URL
Missing schemes, malformed percent escapes, illegal characters or accidental whitespace can fail before the request reaches your application. Puppeteer’s navigation reference lists an invalid target URL as a possible failure. Construct the URL with the platform’s URL API rather than concatenating unescaped user input.
A timeout is a loading problem, not a length measurement
A large query can trigger expensive server work, a slow redirect chain or a page that never reaches your selected waitUntil condition. Puppeteer documents navigation timeouts as a separate failure case. Increasing the timeout may help a slow response, but it cannot make an over-limit browser URL valid.
The main resource failed
SSL errors and main-resource failures are also documented navigation errors. Check the thrown error, certificate configuration and the first response rather than treating all exceptions as URL-size errors.
A redirect changes the URL
The HTTPRequest documentation explains that a redirect creates a new request to the redirected URL. The initial URL may be acceptable while the redirected location is malformed, blocked or substantially longer. Log each request and response in the chain when diagnosing a failure.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsAn HTTP error is still an HTTP response
A 404 or 503 response means the server answered with an HTTP status. It is different from a network failure or a navigation exception. The Puppeteer page documentation describes these distinctions; record the status code and the exception independently.
An intermediary imposes a smaller request-target limit
Load balancers, reverse proxies, web servers, WAFs and API gateways can each apply their own request-line or request-target policy. There is no single number that applies to all products and versions. Identify the component that rejected the request and consult that component’s version-specific configuration instead of quoting a generic “server limit.”
Rank #3
Measure the exact URL before navigating
Characters and bytes are not interchangeable. Non-ASCII characters become multiple UTF-8 bytes, and percent encoding can expand a value. This diagnostic reports both counts, validates the scheme and records the final URL that you actually pass to Chromium.
import puppeteer from 'puppeteer';
const target = process.argv[2];
if (!target) {
throw new Error('Usage: node check-goto.mjs https://example.com/path?query=value');
}
let parsed;
try {
parsed = new URL(target);
} catch {
throw new Error('The target is not a valid absolute URL');
}
if (!['http:', 'https:'].includes(parsed.protocol)) {
throw new Error(`Unsupported scheme: ${parsed.protocol}`);
}
const bytes = new TextEncoder().encode(target).length;
const characters = [...target].length;
console.log({ characters, utf8Bytes: bytes, startsWith: target.slice(0, 80) });
if (bytes >= 2_000_000) {
console.warn('This is at or above an approximate 2 MB browser warning point; Chromium documents 2 MB, not a Puppeteer contract.');
}
const browser = await puppeteer.launch();
const page = await browser.newPage();
page.on('request', request => {
if (request.isNavigationRequest()) {
console.log('navigation request:', request.url());
}
});
page.on('response', response => {
if (response.request().isNavigationRequest()) {
console.log('navigation response:', response.status(), response.url());
}
});
try {
await page.goto(target, {
waitUntil: 'domcontentloaded',
timeout: 30_000
});
console.log('navigation completed');
} catch (error) {
console.error('navigation failed:', error.message);
process.exitCode = 1;
} finally {
await browser.close();
}The 2,000,000-byte warning in this example is deliberately a diagnostic approximation. Chromium’s documentation says “2 MB” but does not turn that phrase into a Puppeteer-configurable byte constant. Treat the warning as a prompt to redesign or test the exact Chrome version and deployment path.
Designs that avoid oversized navigation URLs
Send large data in a request body
If the operation is yours to design, put a large filter, document or parameter set in a POST body. A body avoids putting all data in the request target, where browser, proxy and logging limits are commonly tighter. This is an application architecture choice, not a special Puppeteer requirement.
Store the data and navigate with a short token
Persist the state server-side, generate a random identifier and navigate to a compact URL such as https://app.example/report/7f3.... Expire tokens, authorize access and avoid putting secrets in query strings that may appear in browser history, proxy logs or analytics.
Encode only what must be encoded
Use URL and URLSearchParams so delimiters are escaped correctly. Base64, JSON and repeated percent encoding can make a URL much larger; choose a compact representation or a server-side token when the data grows.
Keep redirects under control
Have the first response redirect directly to the final, short canonical URL. A chain that repeatedly appends parameters can produce a final request that is much larger than the original input.
A practical troubleshooting sequence
- Capture the exact input. Log the URL passed to
page.goto()securely, including its byte count. Redact credentials and sensitive query values. - Parse it locally. Require an absolute
httporhttpsURL and reject malformed escapes or unsupported schemes. - Run the smallest navigation. Use
waitUntil: 'domcontentloaded'and a finite timeout so a slow application is not confused with a URL-size failure. - Log the request chain. Record every navigation request, redirect location and response status. The failing URL may be a later redirect.
- Compare paths. Test the same URL with a direct HTTP client and through the production proxy. A difference points to an intermediary or server policy, not necessarily Puppeteer.
- Check the browser build. Confirm the Chrome/Chromium version used by your Puppeteer installation and reproduce with that binary. The 2 MB figure is Chromium documentation, not a cross-browser guarantee.
- Redesign when the URL is near the ceiling. Move large state to a body or a short-lived server-side token instead of relying on a boundary that can vary across the request path.
Reliability, performance and cost considerations
Long URLs consume memory in the browser, server access logs, tracing systems and monitoring pipelines. They can also increase parsing and authorization work before your application renders anything. Even when a URL is accepted, a compact token generally gives you more predictable behavior across redirects and infrastructure.
Do not solve a length problem by setting an unlimited navigation timeout. A longer timeout changes how long Puppeteer waits; it does not change Chromium’s URL handling or a proxy’s request-target policy. Likewise, retrying an invalid or rejected URL usually adds load without changing the outcome. Classify failures first, then retry only transient network or server conditions.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your actual goal is to obtain an image or PDF of a page represented by a long URL, ScreenshotNeo provides a single screenshot API call instead of requiring you to provision and script a browser. Its capture flow accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms along with newsletter popups and chat widgets; each cleanup step can be disabled. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers.
For developers using AI tools, ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. Every plan includes the features; the free plan provides 1,000 shots per month without a card, and paid plans start at $5 for 3,000 shots.
Use the API directly (replace the target URL with your own encoded URL):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpEquivalent Python:
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)Equivalent Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo API documentation for the 63 capture options, including full-page and element shots, device presets, custom headers and cookies, waits, request blocking, caching, signed links, asynchronous jobs and bulk capture. Create a free ScreenshotNeo account to use the 1,000-shots-per-month allowance with no card.
Bottom line
Puppeteer does not define a page.goto() URL maximum. For Chrome or Chromium, plan around the documented 2 MB browser ceiling, while remembering that servers and intermediaries may impose lower limits. Validate and measure the exact URL, inspect redirects and response errors, and move large state into a request body or server-side token when reliability matters.
Frequently Asked Questions
Should query strings contain secrets when I am debugging URL length?
Prefer not to. Query strings can be copied into browser history, proxy logs, access logs and analytics. Redact sensitive values in diagnostics and use an authorized, short-lived server-side token or a request body for confidential data.
Does percent-encoding change the length calculation?
Yes. The browser receives the encoded URL string, so measure the final string passed to page.goto(), not an earlier unescaped representation. UTF-8 byte length and visible character count can differ.
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.
