# Node migration troubleshooting

## Cannot find module

Run `deno install` first. If the package is declared in `package.json` but a tool needs a physical directory, choose `nodeModulesDir: "auto"` or retain manual mode. Do not copy dependencies by hand.

```bash
deno info src/main.ts
deno check src/main.ts
```

## require is not defined

Prefer converting your own code to ESM. When CommonJS must remain, use `.cjs` or set `"type": "commonjs"` in the nearest `package.json`. Do not hide the boundary with a fake global `require`.

## An npm package resolves but fails at runtime

Check, in order:

1. Node-API native addons;
2. required install or postinstall scripts;
3. assumptions about a writable `node_modules`;
4. ungranted environment, certificate, or config-file access;
5. Node API behavior that is not yet compatible.

## Tests pass on Node but fail on Deno

Keep the original runner at first and execute it under Deno; do not migrate to `Deno.test` in the same step. Inspect globals, fake timers, snapshot paths, environment variables, and temporary directories. Convert tests only after a compatibility baseline exists.

## PermissionDenied

This is evidence of missing access, not a reason to add `-A`. Use `DENO_TRACE_PERMISSIONS=1` or permission auditing to identify the resource, then grant only the host, variable, command, or directory involved.

See [common errors](/en/docs/reference/errors) for runtime issues. Official references: [Node compatibility](https://docs.deno.com/runtime/fundamentals/node/) and [Migrating from Node](https://docs.deno.com/runtime/migrate/).