How to fix DeprecationWarning: punycode is deprecated

[victornasar]

Summary

When I run pnpm run dev on vscode on a freshly created next project, I get this

next dev

▲ Next.js 14.2.3

• Local: http://localhost:3000

✓ Starting...
✓ Ready in 3.2s
(node:14572) [DEP0040] DeprecationWarning: The punycode module is deprecated. Please use a userland alternative instead.
(Use node --trace-deprecation ... to show where the warning was created)
○ Compiling / ...
(node:14572) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
✓ Compiled / in 2.1s (532 modules)

I don't know how this warning is triggered. I used node --trace-deprecation ..., but I get this error

victornasar@My-MacBook-Pro project1 % node --trace-deprecation ...

node:internal/modules/cjs/loader:1189
throw err;
^
Error: Cannot find module '/Users/victornasar/Documents/project1/...'
at Module._resolveFilename (node:internal/modules/cjs/loader:1186:15)
at Module._load (node:internal/modules/cjs/loader:1012:27)
at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:158:12)
at node:internal/main/run_main_module:30:49 {
code: 'MODULE_NOT_FOUND',
requireStack: []
}

Node.js v22.2.0

I use homebrew to install node and pnpm.
npm: '10.7.0',
node: '22.2.0',

Additional information

{
  "name": "project1",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "react": "^18",
    "react-dom": "^18",
    "next": "14.2.3"
  },
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "postcss": "^8",
    "tailwindcss": "^3.4.1",
    "eslint": "^8",
    "eslint-config-next": "14.2.3"
  }
}

Example

No response

[icyJoseph]

• https://nodejs.org/api/punycode.html

In this case the issue is that, Node itself is removing this module from its API. Any library that relied on it, that you, transitively use, is triggering this warning.

Best you can do is, figure out which one, and go try to help their developers replace punycode with a different module. I don't think it comes from Next.js itself, but I can be wrong of course. I know they use it in some tests, but those are not shipped in the next package, and the next package itself uses an npm package instead.

[victornasar]

From my research, punycode is a dependency for uri.js.

pnpm-lock.yaml

[email protected]:
dependencies:
punycode: 2.3.1

[carry0987]

From my research, punycode is a dependency for uri.js.

So...we just need to wait for NextJS's maintainer to remove this package?

[icyJoseph]

No, that's not the problem. That's the solution.

The problem is that the native Node.js package, punycode is being deprecated by Node.js itself! And the recommendation is to use the package. What a time to be alive.

[carry0987]

What a time to be alive. <--

As a developer, your last sentence cracked me up.
Indeed, it's not just NextJS, even Jest and Vitest are showing this annoying error.
What a time to be alive. lol

[yunusorak]

When I updated the Next Js version, I got rid of this error in the next projects

[matiasperrone-commandlink]

What about the README in the punycode that says that you should be using

const punycode = require('punycode/');

[arthberman]

just downgrade your version of node to LTS v20.17.0 and it will fix your issue

[Rguezpjm]

After Downgrade my version to 20.17.0 it's saying ERROR: Missing extension name but I've the name already into my package.json. How can I fix it?

[iiljazi]

Hello, I spent some time on this issue and it appears that it is related to the packages that have a dependency on 'punycode' and the syntax they used to include punycode, as was mentioned. If these require statements are fixed and patched the problem should go away. Patching a few packages is not a huge deal, however, if your project contains many packages that depend on punycode then in my opinion it is probably best to just put up with the warning.

The following command should show which packages need to be patched and at which offending files. It recursively searches the ./node_modules tree to find punycode require statements for both variations: require("punycode") & require('punycode'). Note that it will exclude all './file' directives which are just duplicates created by grep. It will also exclude require statement that appear in README files. When there are no offending entries, then the command below should return nothing.

grep -r -e "require('punycode')" -e 'require("punycode")' | grep -v './file:' | grep -v README.md

On some distro's you might need to give the query a target, e.g. '.' (if in node_modules) or 'node_modules/' (if in the root folder of your project):
grep -r -e "require('punycode')" -e 'require("punycode")' . | grep -v './file:' | grep -v README.md

Example: In my project the command returned the following, suggesting 3 offending modules:

% grep -r -e "require('punycode')" -e 'require("punycode")' | grep -v './file:' | grep -v README.md 
./node_modules/@types/node/punycode.d.ts: * const punycode = require('punycode');
./node_modules/whatwg-url/lib/url-state-machine.js:const punycode = require("punycode");
./node_modules/tr46/index.js:var punycode = require("punycode");

Per the punycode documentation I updated the require statements in these files as shown below:

- require('punycode')
- require("punycode")
+ require("punycode/")

Following these changes the deprecation error went away. However, if you follow this procedure and continue to see the issue, then it might be the case that another variation of the require statement is present in your project and not caught by the grep command. Thus, it might be necessary to update the search command accordingly.

Once you have made the changes and confirmed that the issue is addressed, patch the modules in order to ensure that on subsequent installs the changes will be applied retroactively by the patch-package postinstall script. This postinstall script will also let you know when it is time to delete a patch (presuming that the owners of these packages apply the changes in future versions).

Install patch-package:
npm i patch-package

Update package.json:

"scripts" : {
              ...
              + "postinstall": "patch-package",
              ...
}

Create the patches:

npx patch-package <package-name>

Example: Based on the modules impacting my project, I ran the following:

npx patch-package whatwg-url
npx patch-package tr46
npx patch-package @types/node

Start the project (no errors/warnings):

% npm run ios

> [email protected] ios
> react-native run-ios --simulator "iPhone 15 Pro"

info A dev server is already running for this project on port 8081.
info Found Xcode workspace "proj.xcworkspace"

In order to test the patches to ensure that they are retroactively applied on new installations:

rm -rf node_modules/
npm i
npm run ios 

Note: For ios make sure you:
cd ios && pod install

Hope it helps :)

[art3mHQ]

just got this

art3m@MacBook-Pro node_modules % grep -r -e "require('punycode')" -e 'require("punycode")' | grep -v './file:' | grep -v README.md 
grep: warning: recursive search of stdin

no else reply

UPD: grep -r -e "require('punycode')" -e 'require("punycode")' . | grep -v './file:' | grep -v README.md did the trick

[iiljazi]

@art3mHQ I'm not sure why that is. I'm on a Mac running Sonoma and it worked fine as originally authored for me. What distro are you running? In either case, this is very helpful if anyone runs into the same issue you encountered so I've modified the original procedure accordingly.

[art3mHQ]

@iiljazi i'm on macos 11 aka big sur :) thank you for posting, fixed my issue

[PratapRathi]

@iiljazi Thanks for your fix, it works.

[nnoromiv]

I was just battling this deprecation error, and I decided to switch through node versions.

• I do not get the error in node 18 but I get the error in node 22.
• I have also deleted every package the required punycode

I still need a proper solution to this issue, no solution works yet

[ADTC]

You can also use node 20 LTS. No such error.

[florianliebig]

https://nodejs.org/api/punycode.html

The version of the punycode module bundled in Node.js is being deprecated. In a future major version of Node.js this module will be removed. Users currently depending on the punycode module should switch to using the userland-provided Punycode.js module instead. For punycode-based URL encoding, see url.domainToASCII or, more generally, the WHATWG URL API.

This will not break within node v22. So I would just ignore that for now

[cookabc]

I added a .nvmrc file with content:
20

[ikarkam76]

Hi!
After updating Node to version 22, I also encountered this error. It happened in a React Native project, in Next.js, and while running an Express server. I tried almost all the solutions suggested on forums but finally found the cause in my setup. At one point, I had installed Node on my Mac M1 using the installer, and it was version 20, which is typically placed in /usr/local/bin/node. Recently, I updated to version 22 via Homebrew, which installs Node for Apple Silicon Macs in /opt/homebrew/bin/node. It turned out that version 20 was still in /usr/local/bin/node, while version 22 was at /opt/homebrew/bin/node. As far as I understand, the projects were still referencing version 20, even though version 22 was the active one. Deleting version 22 and reverting back to version 20 solved the issue for me. I hope this solution helps someone else!

[brianMxBm]

@ikarkam76 This was the exact situation that I was facing, brew had installed node a dependency somehow and my path for node was wrong. Thank you!

[jeanjerome]

I had to use this command line
grep -rl -e "require('punycode')" -e 'require("punycode")' --exclude='README.md'
to get only the file paths, and I found it in
./node_modules/next/dist/compiled/node-fetch/index.js.

I am using next: "15.0.3" and Node 22.

[djonko]

same from me I am using nextjs 15.1.3 and node 22 .. so what did you do to fix this ?

[wowtah]

After upgrading Node.js from v20 to v22.11.0, I also got this warning in my project.

Traced it down to [email protected]

$ npm ls punycode
[email protected] C:\Users\me\source\repos\my-project
└─┬ [email protected]
  └─┬ [email protected]
    └─┬ [email protected]
      └── [email protected]

I'm using Next.js 14.2.18 (turbo), and as far as I recall eslint-config-next (I use 14.2.18) doesn't work with eslint 9.x yet? Unsure if I am willing to upgrade the project to Next.js 15 yet...

So not sure how to solve the warning, except downgrading Node.js back to v20 maybe?

[daveycodez]

This is happening on Next.js 15 for me so I don't think that will help even

[davecarlson]

npm ls punycode

After upgrading Node.js from v20 to v22.11.0, I also got this warning in my project.

Traced it down to [email protected]

$ npm ls punycode
[email protected] C:\Users\me\source\repos\my-project
└─┬ [email protected]
  └─┬ [email protected]
    └─┬ [email protected]
      └── [email protected]

I'm using Next.js 14.2.18 (turbo), and as far as I recall eslint-config-next (I use 14.2.18) doesn't work with eslint 9.x yet? Unsure if I am willing to upgrade the project to Next.js 15 yet...

So not sure how to solve the warning, except downgrading Node.js back to v20 maybe?

└─┬ @comp/[email protected] -> ./packages/eslint-config-custom
  └─┬ [email protected]
    └─┬ [email protected]
      └─┬ [email protected]
        └── [email protected]

eslint 9 uses the same ajv, so the same issue occurs

[icyJoseph]

This is not the problem... you are supposed to be using the NPM package. The warning is that, you should not use the native punycode module from Node.js

[daveycodez]

npm run dev

> [email protected] dev
> next dev & nodemon --exec node code-sync.js --quiet

   ▲ Next.js 15.0.3
   - Local:        http://localhost:3000
   - Environments: .env.local
   - Experiments (use with caution):
     · scrollRestoration

 ✓ Starting...
 ✓ Ready in 810ms
Code Synced Successfully
 ○ Compiling /login ...
(node:7499) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
 ✓ Compiled /login in 2.7s (2594 modules)
 GET /login 200 in 3051ms

npm ls punycode
[email protected] /Users/david/Developer/daveyplate
└── (empty)

Oof untraceable

[daveycodez]

grep -rl -e "require('punycode')" -e 'require("punycode")' --exclude='README.md'

./node_modules/next/dist/compiled/node-fetch/index.js
./node_modules/whatwg-url/lib/url-state-machine.js
./node_modules/@daveyplate/use-scroll-restoration/node_modules/next/dist/compiled/node-fetch/index.js
./node_modules/tr46/index.js

This helped.. I'll see if I can clean these out. Looks like node-fetch isn't going anywhere, though. Any way to suppress the warning?

[icyJoseph]

Ah yes, it was node-fetch.... the compiled version still uses require("punycode"), rather than require("punycode/") ush...

[ertugrulemrecihan]

Maybe this work for you
https://dev.to/asim_khan_cbe65e41bcbbc65/solving-the-punycode-module-is-deprecated-issue-in-nodejs-2e59

[toyamarinyon]

if you face this waning with openai-node, it prevents with v5.0.0-alpha0

openai/openai-node#527