# Fix the punycode Deprecation Warning (DEP0040) in a Node.js Project

Yes. An agent traces the punycode warning to the dependency that loads it, removes that dependency or moves past it, and shows a clean start on each Node version.

[Run this on Rush](https://cloud.getrush.ai/run/fix-punycode-deprecation-warning/nodejs/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

`[DEP0040] DeprecationWarning: The punycode module is deprecated. Please use a userland alternative instead.` almost never comes from your own code. Some package in `node_modules` calls `require('punycode')` and gets Node's built-in copy. The agent's first job is to name that package, and its second is to reproduce the warning on a Node version that prints it, which takes more care than it sounds. In a library like 1999/node-couchdb, `package.json` has two runtime dependencies, `node-fetch` `^2` and `abort-controller` `^3.0.0`, and `engines` says `node >=14`. Loading the package prints the warning on some Node releases and nothing on others: in the agent's checks a 20 release is silent, 21 and early 22 releases warn, and later 22 releases and 24 are silent again when the `require` comes from inside `node_modules`. A developer on a new Node who sees no warning has not fixed anything.

So the agent installs from `package-lock.json`, runs the package under several Node versions with `npx node@<version>`, and on one that warns adds `--trace-deprecation`. The stack points at `node_modules/whatwg-url/lib/url-state-machine.js`, and `npm ls whatwg-url tr46` shows the chain: `node-fetch@2.6.7` depends on `whatwg-url@5.0.0`, which depends on `tr46@0.0.3`, and both of the last two load the built-in module. node-fetch 2 pins that old `whatwg-url`, so no update inside its major changes this.

There are three ways out and the agent says which fits. An `overrides` entry in `package.json` that forces a newer `whatwg-url` works for an application, but npm applies overrides only from the root project, so a published library that adds one fixes its own test runs and nobody else's. Suppressing the warning with `NODE_OPTIONS=--no-deprecation` hides every other deprecation too. For a library the fix is to stop depending on the package. Here `src/node-couchdb.js` imports `fetch` from `node-fetch` and `AbortController` from `abort-controller` and uses them in one request function with a timeout; both are globals in current Node, so the agent deletes the two imports and the two dependencies. `test/test.js` imports `fetch` and `Headers` from `node-fetch` as well, and that import changes in the same commit, or the suite cannot load.

Removing them has a price the agent states in the pull request: global `fetch` arrived in Node 18, so `engines` moves from `>=14` to `>=18`, the `14` entry leaves `.travis.yml`, and the change is a major version for the package. It then proves the result. It rebuilds `dist` with the `build` script, confirms `npm ls` no longer lists `whatwg-url` or `tr46`, and loads the package on each Node version from before to show no warning. Since the test suite talks to a live CouchDB with credentials from the environment, it also starts a small local HTTP server that answers `/_all_dbs` and calls `listDatabases()` through the built package, before and after.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "This Node.js project prints [DEP0040] DeprecationWarning: The punycode module is deprecated. Find the cause and fix it at the source. Install from the lockfile. Reproduce the warning first: load the package's main entry (and run its CLI or start script if it has one) under several Node versions using npx node@<version>, covering the oldest version engines allows, the versions in the CI config, and at least 20, 21, an early 22, the latest 22 and the latest release; record which print the warning, because Node versions differ on when it is shown. On a version that prints it, run with --trace-deprecation and report the file that requires punycode. Run npm ls for that package and show the full chain from a dependency in package.json down to it. Search the project's own source for require('punycode') or an import of it; if found, switch it to the userland package with a trailing slash in the specifier or to the URL API, and add the dependency. For a dependency that causes it, choose in this order and explain the choice: remove the dependency if Node now provides what it did (fetch, AbortController, URL); upgrade it to a release that no longer loads the built-in module; only for an application that is not published as a library, add an npm overrides entry for the transitive package. Never silence it with --no-deprecation, NODE_NO_WARNINGS or a process.removeAllListeners call. If the fix raises the minimum Node version, change engines, the CI matrix, the README and the changelog together and say the change is breaking. Update test files that import a removed package. Rebuild any committed or published build output with the project's build script. Verify: npm ls no longer shows the package that required punycode; loading the entry on every Node version from the first step prints no deprecation warning; the test suite passes, or, if it needs an external service you cannot start, say so and exercise one real request path against a local stub HTTP server before and after. Open a pull request with the version table, the trace and the npm ls output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that removes two import lines from `src/node-couchdb.js`, empties `dependencies` in `package.json`, raises `engines`, updates `package-lock.json`, the import in `test/test.js` and the Node list in `.travis.yml`, and adds a `HISTORY.md` entry that calls the release breaking. The description has a table with one row per Node version and two columns, warning before and warning after, the `--trace-deprecation` stack, and the `npm ls` output for `whatwg-url` before and after.

The reviewer checks the request function still does what it did with the built-in `fetch`: the abort timer is cleared in `finally`, a non-2xx response still resolves with `res.ok` false as the callers expect, and response headers are still read with `res.headers.get`. They also weigh the version bump. If dropping Node 14 and 16 is not acceptable yet, the description names the fallback, which is to keep `node-fetch` and accept the warning until those runtimes go, since no node-fetch 2 release avoids it.

What was not run is stated. `.travis.yml` starts CouchDB and memcached as services and the tests read `COUCHDB_USER` and `COUCHDB_PASS`; the run has no database and no credentials, so the suite is listed as not executed and the stub server check stands in for one request path only. The pull request asks for one CI run against a real database before release.

## Run it on every Node.js version bump

Deprecation warnings arrive with a runtime upgrade, so the natural trigger is the pull request that changes the Node version. In the Project, add an automation with a `github` trigger on `pull_request.opened`, filtered by a label such as `node-upgrade`, and a prompt that asks the agent to start the application on the new version, list every deprecation warning with its `--trace-deprecation` source, and fix the ones caused by dependencies. The pull request event is added after the prompt as data.

To check a fleet of services once, call `POST /o/{org}/sessions` with this body per repository and a `request_id` that is a UUID v5 of the repository name. Each call answers `202`; read the sessions as they complete.

## Why run it on Rush?

Whether this warning appears depends on the exact Node release, so one machine cannot answer the question. The agent downloads the versions it needs into its sandbox, runs the same entry point under each and keeps every output. The table in the pull request is built from those runs, and the transcript shows the command behind each row, including the versions where the warning is hidden without being fixed.

It also keeps the fix honest. The fast way to make a warning disappear is a flag in a start script, and nobody reviewing a one-line change to `package.json` scripts will object. The prompt rules that out, and the proof asked for is structural: the package that required the module is absent from `npm ls`. That holds on any Node version, present or future.

## Frequently asked questions

### How do I find which package is using punycode?

Run your entry point with `node --trace-deprecation` on a Node version that prints the warning. The stack trace names the file that called `require('punycode')`. Then `npm ls <that package>` shows which of your direct dependencies brings it in.

### Why did the warning disappear after I upgraded Node, without changing anything?

Newer Node releases stopped printing this warning when the `require` comes from a file inside `node_modules`. The old dependency is still installed and still loads the deprecated module; you just are not told. Check with `npm ls whatwg-url tr46` instead of trusting a quiet console.

### Can I fix it with npm overrides?

In an application, yes: an `overrides` entry can force a newer version of the transitive package, and you should run your tests afterwards because the parent was not written against it. In a library, no. Overrides are read only from the root `package.json` of whoever runs the install, so yours are ignored when someone depends on your package.

### Is it safe to just ignore it?

It is a warning, and the built-in module still works today. The risks are that it hides other warnings once people start suppressing output, and that the dependency behind it is usually old enough to carry other problems. Removing a fetch polyfill that Node no longer needs is a small change with a clear end state.

### What if my own code imports punycode?

Install the `punycode` package from npm and import it as `punycode/` with the trailing slash, which makes Node resolve the installed package and not the built-in one. If you only use it to convert domain names, the `URL` class or `url.domainToASCII` may replace it with no dependency at all.

## More Node.js jobs

- [Fix "[DEP0169] DeprecationWarning: url.parse() behavior is not standardized"](https://getrush.ai/run/fix-url-parse-deprecation-warning/nodejs/)
- [Fix Vulnerable Dependencies in a Node.js App](https://getrush.ai/run/fix-vulnerable-dependencies/nodejs/)
- [Migrate a Node.js App from CommonJS to ESM](https://getrush.ai/run/migrate-commonjs-to-esm/nodejs/)

## More jobs like this: Upgrade dependencies weekly

- [Fix "AttributeError: module 'pytest' has no attribute 'config'" After Upgrading pytest](https://getrush.ai/run/fix-pytest-config-attribute-error/pytest/)
- [Fix "PytestRemovedIn10Warning: @pytest.yield_fixture is deprecated" Before pytest 10 Removes It](https://getrush.ai/run/fix-pytest-yield-fixture-is-deprecated-warning/pytest/)
- [Fix "Warning: ReactDOMTestUtils.act is deprecated in favor of React.act" in React Testing Library Tests](https://getrush.ai/run/fix-reactdomtestutils-act-is-deprecated-warning/testing-library/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
