Node migration troubleshooting
Diagnose module resolution, CommonJS, native addons, permissions, and test differences
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.
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:
- Node-API native addons;
- required install or postinstall scripts;
- assumptions about a writable
node_modules; - ungranted environment, certificate, or config-file access;
- 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 for runtime issues. Official references: Node compatibility and Migrating from Node.