Issue Station
Sign In
Tools hereToolbox

nextjs - ✅(Solved) Fix Docs: deprecated `url.parse()` call used in custom server example [2 pull requests, 8 comments, 5 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#86951•Fetched 2026-04-08 02:08:17
View on GitHub
Comments
8
Participants
5
Timeline
18
Reactions
0
Author
altendkyaltendky
Participants
altendkyaltendkyashishs10ashishs10azadgupta1azadgupta1github-actions[bot]github-actions[bot]icyJosephicyJoseph
Timeline (top)
commented ×8cross-referenced ×2labeled ×2closed ×1

Error Message

i started exploring this situation after i got the following (slightly snipped) traceback when running code similar to the example.

Fix Action

Fixed

PR fix notes

PR #86972: docs: remove deprecated url.parse() from custom server example

Description (problem / solution / changelog)

This PR updates the custom server documentation to remove usage of Node's deprecated url.parse() API. The example does not require URL parsing, since the parsedUrl argument is optional for the Next.js RequestHandler.

Removing url.parse() avoids Node deprecation warnings (DEP0116, DEP0169) and aligns the example with current best practices.

This implements the minimal fix suggested in issue #86951.

Why?

  • url.parse() is deprecated in modern Node versions.
  • The example works without URL parsing.
  • Keeps documentation aligned with recommended APIs.

How?

  • Removed url.parse() import.
  • Removed parsedUrl creation.
  • Updated both TS and JS examples to simply call handle(req, res).

Fixes #86951

Changed files

  • .github/workflows/build_and_deploy.yml (modified, +2/-2)
  • .github/workflows/build_and_test.yml (modified, +5/-9)
  • .github/workflows/build_reusable.yml (modified, +3/-1)
  • .github/workflows/pull_request_stats.yml (modified, +3/-1)
  • crates/next-api/src/app.rs (modified, +3/-7)
  • crates/next-api/src/nft_json.rs (modified, +33/-0)
  • crates/next-core/src/next_app/metadata/route.rs (modified, +88/-23)
  • crates/next-core/src/pages_structure.rs (modified, +2/-2)
  • docs/01-app/01-getting-started/01-installation.mdx (modified, +43/-3)
  • docs/01-app/01-getting-started/02-project-structure.mdx (modified, +37/-20)
  • docs/01-app/01-getting-started/08-updating-data.mdx (modified, +5/-1)
  • docs/01-app/01-getting-started/14-metadata-and-og-images.mdx (modified, +11/-4)
  • docs/01-app/01-getting-started/15-route-handlers-and-middleware.mdx (modified, +3/-3)
  • docs/01-app/02-guides/backend-for-frontend.mdx (modified, +10/-1)
  • docs/01-app/02-guides/content-security-policy.mdx (modified, +2/-2)
  • docs/01-app/02-guides/custom-server.mdx (modified, +4/-4)
  • docs/01-app/02-guides/data-security.mdx (modified, +4/-0)
  • docs/01-app/02-guides/forms.mdx (modified, +1/-1)
  • docs/01-app/02-guides/incremental-static-regeneration.mdx (modified, +2/-2)
  • docs/01-app/02-guides/internationalization.mdx (modified, +1/-0)
  • docs/01-app/02-guides/json-ld.mdx (modified, +1/-1)
  • docs/01-app/02-guides/lazy-loading.mdx (modified, +1/-0)
  • docs/01-app/02-guides/local-development.mdx (modified, +3/-3)
  • docs/01-app/02-guides/package-bundling.mdx (modified, +1/-1)
  • docs/01-app/02-guides/videos.mdx (modified, +2/-2)
  • docs/01-app/03-api-reference/02-components/image.mdx (modified, +5/-2)
  • docs/01-app/03-api-reference/02-components/link.mdx (modified, +7/-0)
  • docs/01-app/03-api-reference/03-file-conventions/01-metadata/manifest.mdx (modified, +1/-1)
  • docs/01-app/03-api-reference/03-file-conventions/dynamic-routes.mdx (modified, +20/-0)
  • docs/01-app/03-api-reference/03-file-conventions/error.mdx (modified, +1/-1)
  • docs/01-app/03-api-reference/03-file-conventions/instrumentation.mdx (modified, +1/-1)
  • docs/01-app/03-api-reference/03-file-conventions/layout.mdx (modified, +4/-3)
  • docs/01-app/03-api-reference/03-file-conventions/middleware.mdx (modified, +19/-3)
  • docs/01-app/03-api-reference/03-file-conventions/page.mdx (modified, +1/-0)
  • docs/01-app/03-api-reference/03-file-conventions/route.mdx (modified, +1/-1)
  • docs/01-app/03-api-reference/04-functions/after.mdx (modified, +1/-1)
  • docs/01-app/03-api-reference/04-functions/cookies.mdx (modified, +8/-0)
  • docs/01-app/03-api-reference/04-functions/fetch.mdx (modified, +1/-1)
  • docs/01-app/03-api-reference/04-functions/generate-metadata.mdx (modified, +12/-11)
  • docs/01-app/03-api-reference/04-functions/next-response.mdx (modified, +48/-2)
  • docs/01-app/03-api-reference/04-functions/revalidatePath.mdx (modified, +6/-4)
  • docs/01-app/03-api-reference/04-functions/use-pathname.mdx (modified, +52/-0)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/htmlLimitedBots.mdx (modified, +43/-2)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/middlewareClientMaxBodySize.mdx (added, +118/-0)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/output.mdx (modified, +63/-2)
  • docs/01-app/03-api-reference/05-config/01-next-config-js/rewrites.mdx (modified, +5/-4)
  • docs/01-app/03-api-reference/05-config/02-typescript.mdx (modified, +152/-13)
  • docs/01-app/03-api-reference/06-cli/next.mdx (modified, +4/-1)
  • docs/01-app/03-api-reference/08-turbopack.mdx (modified, +1/-1)
  • docs/02-pages/02-guides/internationalization.mdx (modified, +1/-1)
  • docs/02-pages/04-api-reference/04-config/01-next-config-js/middlewareClientMaxBodySize.mdx (added, +7/-0)
  • lerna.json (modified, +4/-3)
  • package.json (modified, +2/-2)
  • packages/create-next-app/index.ts (modified, +9/-1)
  • packages/create-next-app/package.json (modified, +1/-1)
  • packages/create-next-app/templates/app-tw-empty/js/biome.json (modified, +4/-1)
  • packages/create-next-app/templates/app-tw-empty/ts/biome.json (modified, +4/-1)
  • packages/create-next-app/templates/app-tw/js/biome.json (modified, +4/-1)
  • packages/create-next-app/templates/app-tw/ts/biome.json (modified, +4/-1)
  • packages/create-next-app/templates/default-tw-empty/js/biome.json (modified, +4/-1)
  • packages/create-next-app/templates/default-tw-empty/ts/biome.json (modified, +4/-1)
  • packages/create-next-app/templates/default-tw/js/biome.json (modified, +4/-1)
  • packages/create-next-app/templates/default-tw/ts/biome.json (modified, +4/-1)
  • packages/eslint-config-next/package.json (modified, +2/-2)
  • packages/eslint-plugin-internal/package.json (modified, +1/-1)
  • packages/eslint-plugin-next/package.json (modified, +1/-1)
  • packages/font/package.json (modified, +1/-1)
  • packages/font/src/google/loader.test.ts (modified, +0/-1)
  • packages/font/src/local/loader.test.ts (modified, +0/-33)
  • packages/font/src/local/loader.ts (modified, +1/-6)
  • packages/next-bundle-analyzer/package.json (modified, +1/-1)
  • packages/next-codemod/package.json (modified, +1/-1)
  • packages/next-env/package.json (modified, +1/-1)
  • packages/next-mdx/package.json (modified, +1/-1)
  • packages/next-plugin-storybook/package.json (modified, +1/-1)
  • packages/next-polyfill-module/package.json (modified, +1/-1)
  • packages/next-polyfill-nomodule/package.json (modified, +1/-1)
  • packages/next-rspack/package.json (modified, +1/-1)
  • packages/next-swc/package.json (modified, +1/-1)
  • packages/next/config.js (modified, +12/-1)
  • packages/next/errors.json (modified, +4/-1)
  • packages/next/font/index.d.ts (modified, +0/-1)
  • packages/next/package.json (modified, +7/-7)
  • packages/next/src/build/templates/app-page.ts (modified, +1/-2)
  • packages/next/src/build/templates/app-route.ts (modified, +1/-2)
  • packages/next/src/build/webpack-config.ts (modified, +0/-1)
  • packages/next/src/build/webpack/config/blocks/css/loaders/next-font.ts (modified, +0/-1)
  • packages/next/src/build/webpack/config/index.ts (modified, +0/-3)
  • packages/next/src/build/webpack/config/utils.ts (modified, +0/-1)
  • packages/next/src/build/webpack/loaders/devtool/devtool-style-inject.js (modified, +39/-31)
  • packages/next/src/build/webpack/loaders/next-font-loader/index.ts (modified, +1/-3)
  • packages/next/src/bundles/babel-code-frame/index.js (added, +3/-0)
  • packages/next/src/bundles/babel/bundle.js (modified, +0/-5)
  • packages/next/src/bundles/babel/packages/code-frame.js (modified, +1/-1)
  • packages/next/src/client/components/router-reducer/aliased-prefetch-navigations.ts (modified, +19/-0)
  • packages/next/src/client/components/router-reducer/reducers/navigate-reducer.ts (modified, +1/-1)
  • packages/next/src/compiled/babel-code-frame/LICENSE (added, +22/-0)
  • packages/next/src/compiled/babel-code-frame/index.js (added, +1/-0)
  • packages/next/src/compiled/babel-code-frame/package.json (added, +1/-0)
  • packages/next/src/compiled/babel/bundle.js (modified, +1/-1)

PR #86986: docs: remove deprecated url.parse() from custom server example

Description (problem / solution / changelog)

This PR updates the custom server documentation to remove usage of Node's deprecated url.parse() API. The example does not require URL parsing, since the parsedUrl argument is optional for the Next.js RequestHandler.

Removing url.parse() avoids Node deprecation warnings (DEP0116, DEP0169) and keeps the example aligned with current best practices.

What changed?

  • Removed the url.parse() import and usage.
  • Removed unused parsedUrl variable.
  • Updated both TS and JS examples to use handle(req, res) directly.

Why?

  • url.parse() is deprecated in modern Node versions.
  • The example works without URL parsing.
  • Simplifies the docs and matches recommended APIs.

Fixes #86951 and https://github.com/vercel/next.js/issues/83183

Changed files

  • docs/01-app/02-guides/custom-server.mdx (modified, +4/-4)

Code Example

(node:3243635) [DEP0169] DeprecationWarning: `url.parse()` behavior is not standardized and prone to errors that have security implications. Use the WHATWG URL API instead. CVEs are not issued for `url.parse()` vulnerabilities.
    at urlParse (node:url:136:13)
    at Server.<anonymous> (file:///home/altendky/repos/<snip>/server.js:38:21)
    at Server.emit (node:events:508:28)
    at parserOnIncoming (node:_http_server:1186:12)
    at HTTPParser.parserOnHeadersComplete (node:_http_common:123:17)
RAW_BUFFERClick to expand / collapse

What is the documentation issue?

the legacy url api is deprecated. i expect that deprecated APIs should not be encouraged in examples.

https://nodejs.org/api/deprecations.html#DEP0116

The legacy URL API is deprecated. This includes url.format(), url.parse(), url.resolve(), and the legacy urlObject. Please use the WHATWG URL API instead.

this is one example case. others should be searched for in this file and beyond if a change is made.

https://github.com/vercel/next.js/blob/78660a53864b8dfff75e8e122cc1db5e8a8d0e4b/docs/01-app/02-guides/custom-server.mdx?plain=1#L29-L32

the parsedUrl parameter for RequestHandler is optional.

https://github.com/vercel/next.js/blob/78660a53864b8dfff75e8e122cc1db5e8a8d0e4b/packages/next/src/server/next.ts#L64-L68

i would (with minimal next.js experience...) suggest simply removing the parsing entirely from the example or updating to the whatwg url api. if there is agreement on the path forward i could provide a pr for consideration.

or... maybe you'll tell me why this is nonsense and i'll learn a little something. :] thanks for your time.

Is there any context that might help us understand?

i started exploring this situation after i got the following (slightly snipped) traceback when running code similar to the example.

(node:3243635) [DEP0169] DeprecationWarning: `url.parse()` behavior is not standardized and prone to errors that have security implications. Use the WHATWG URL API instead. CVEs are not issued for `url.parse()` vulnerabilities.
    at urlParse (node:url:136:13)
    at Server.<anonymous> (file:///home/altendky/repos/<snip>/server.js:38:21)
    at Server.emit (node:events:508:28)
    at parserOnIncoming (node:_http_server:1186:12)
    at HTTPParser.parserOnHeadersComplete (node:_http_common:123:17)

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/pages/guides/custom-server

extent analysis

TL;DR

Update the example to use the WHATWG URL API instead of the deprecated legacy URL API.

Guidance

  • Review the example code in the custom server guide and identify all instances of the legacy URL API, including url.format(), url.parse(), and url.resolve().
  • Replace these instances with their equivalents in the WHATWG URL API, such as URL() and URL.prototype.toString().
  • Verify that the updated example code works as expected and does not produce any deprecation warnings.
  • Consider submitting a pull request with the updated example code for review and inclusion in the Next.js documentation.

Example

// Before
const url = require('url');
const parsedUrl = url.parse('https://example.com');

// After
const parsedUrl = new URL('https://example.com');

Notes

The legacy URL API is deprecated and may be removed in future versions of Node.js, so it's essential to update the example code to use the WHATWG URL API to ensure compatibility and security.

Recommendation

Apply workaround: Update the example code to use the WHATWG URL API to avoid deprecation warnings and ensure future compatibility.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#container setup#orchestration issue#cache issue#memory leak

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

nextjs - ✅(Solved) Fix Docs: deprecated `url.parse()` call used in custom server example [2 pull requests, 8 comments, 5 participants]