Start with the error and the command that produced it
An import error means a tool could not load code in the way your project requested. The cause might be a misspelled file path, an uninstalled package, an incompatible module format, or a package that does not expose the path you requested. Before changing anything, copy the full error message and note the command you ran. The first useful clue is often the module name or file path in the message; another is the file that tried to import it.
For the Node.js examples below, use Node.js 20 or newer and the npm version supplied with it. Check your tools with node --version and npm --version. Run project commands from the directory containing package.json unless the project’s instructions say otherwise. If an editor reports an error but the command-line program runs, check whether the editor has opened the right project folder and is using the intended tools. Diagnose the command-line failure separately from an editor warning.
Decide whether the import names a file or a package
A relative import begins with ./ or ../ and points to a file relative to the importing file, not necessarily the project root. If src/main.js contains import { format } from './format.js', Node looks for src/format.js. Check the directory, filename, capitalization, and extension. Capitalization matters on many systems, so an import that appears to work on one computer may fail on another. In Node’s ECMAScript module mode, include the .js extension for a relative JavaScript file import.
You can make a small check without installing a package. Create a package.json containing {"type":"module"}. Put export function format(value) { return String(value); } in src/format.js, and put import { format } from './format.js'; console.log(format(42)); in src/main.js. From the package directory, run node src/main.js. It should print 42. If you change './format.js' to './formats.js', the resulting error points to a path problem, not a missing npm dependency.
A bare import, such as import something from 'package-name', asks Node to resolve a package. Do not try to fix it by adding ./ unless you actually meant to import a local file. Likewise, a browser loading JavaScript directly does not resolve npm package names the same way Node does. If an import works in a build tool but fails when you open a script directly in the browser, check whether the project expects a development server, bundler, or import map.
Check installation and project boundaries
For a package import, first look in package.json for the dependency and run npm ls package-name from the project directory, replacing package-name with the name in the error. This helps distinguish a declared dependency from one available in the current installation. If the project has a package-lock.json, npm ci installs from that lockfile and is useful for checking a reproducible setup; it replaces the existing node_modules directory. If there is no lockfile, npm install uses the declared dependencies and may create one.
Avoid deleting the lockfile as a first troubleshooting step. It records resolved package versions, and removing it can change the dependency tree instead of explaining the original problem. Also check whether you are in the correct package of a multi-package repository: a dependency declared in one package is not automatically available everywhere. If installation itself fails, read that error first. A network, permission, or package-version failure cannot be repaired by rewriting import statements.
Match the import to the module’s public interface
A module can be found but still fail to provide the export you requested. Compare import { name } from './file.js' with export const name = ... in that file. A default export instead uses a default import, without braces. If Node reports a syntax or module-format error, inspect package.json for "type":"module" and check the file extension. Node.js projects may use ECMAScript modules or CommonJS; copying an import or require statement from a project using the other format can produce a confusing failure.
For third-party packages, check the package’s installed version and its documented import entry points. Some packages restrict subpaths through an exports field in their package.json. In that case, a path that exists inside node_modules is not necessarily a supported path to import. Prefer the package’s public entry point over reaching into its internal files. If an example you followed targets a different package version, adapt the import or select an appropriate version deliberately rather than guessing at internal paths.
Verify the smallest fix and leave a useful trail
Change one likely cause at a time, then rerun the exact command that failed. If the error changes, read the new message instead of assuming the whole problem is solved. Once it runs, try the project’s normal test or build command too, if one is provided. A direct Node command and a development server may use different resolution rules, so both checks can matter.
When documenting the fix for yourself or a teammate, record the command, relevant tool versions, the original error, the root cause, and the change that resolved it. For example, “src/main.js imported './format' in a Node.js ECMAScript module project; changing it to './format.js' fixed node src/main.js” is more useful than “reinstalled everything.” That note turns an isolated repair into a repeatable debugging method.
