This page covers how to file effective bug reports for module resolution problems in TypeScript. It describes what information is required, how to create a minimal reproduction, and provides technical context about how TypeScript's module resolution works so reporters can identify what is relevant.
For general bug report guidance, see 15.5 For feature requests related to how module resolution should behave, see 15.6 For changes to standard library type declarations, see 15.7
A module resolution issue is a bug where TypeScript either:
Cannot find module).js or .d.ts filesmoduleResolution strategies for equivalent setupspackage.json exports/imports fieldsThese are distinct from type errors inside an already-resolved module (which is a type-checking issue, not a resolution issue).
The following diagnostic codes in src/compiler/diagnosticMessages.json are common indicators of module resolution problems:
| Code | Message (abbreviated) | Typical Cause |
|---|---|---|
| 2307 | Cannot find module '{0}' or its corresponding type declarations | Module not found under any resolution strategy |
| 2792 | Cannot find module '{0}'. Did you mean to set moduleResolution to 'node16' or 'nodenext'? | ESM-style path used under Node10 resolution |
| 7016 | Could not find a declaration file for module '{0}' | .js library without .d.ts files |
| 2306 | File '{0}' is not a module | File found but has no exports |
| 1471 | Relative import paths need explicit file extensions in ECMAScript imports | Missing .js extension under node16/nodenext |
| 2305 | Module '{0}' has no exported member '{1}' | Package exports field blocks access to a subpath |
| 2742 | The inferred type cannot be named without a reference to '{0}' | Resolved type refers to an inaccessible module |
Sources: src/compiler/diagnosticMessages.json1-100
Understanding the resolution pipeline helps identify what information to include in a bug report.
Module Resolution Pipeline
Sources: src/compiler/moduleNameResolver.ts1-100 src/compiler/types.ts1-50 src/compiler/program.ts1-100
Key Code Entities in Module Resolution
Sources: src/compiler/moduleNameResolver.ts1-200 src/compiler/program.ts270-325 src/compiler/types.ts1-100
The moduleResolution compiler option selects the algorithm. The value is represented by ModuleResolutionKind in src/compiler/types.ts.
moduleResolution value | ModuleResolutionKind | When to use |
|---|---|---|
classic | Classic = 1 | Legacy; rarely correct for modern projects |
node / node10 | Node10 = 2 | CommonJS Node.js projects |
node16 | Node16 = 3 | Node.js ESM with package.json exports |
nodenext | NodeNext = 99 | Latest Node.js module semantics |
bundler | Bundler = 100 | Webpack/Vite/esbuild projects with TypeScript source |
The module compiler option also implicitly constrains which moduleResolution values are valid. For example, module: node16 requires moduleResolution: node16.
Sources: src/compiler/commandLineParser.ts1-150 src/compiler/types.ts1-100
A bug report must include all options that could affect resolution. Many are interdependent.
| Option | Effect on Resolution |
|---|---|
moduleResolution | Selects the lookup algorithm |
module | Determines emit format and constrains moduleResolution |
baseUrl | Root for non-relative specifiers |
paths | Path aliases mapped relative to baseUrl |
rootDirs | Virtual directory merging for source trees |
typeRoots | Where to search for @types packages |
types | Explicit list of @types to include |
esModuleInterop | Adds synthetic default import support for CJS modules |
allowSyntheticDefaultImports | Suppresses error for missing default exports |
resolveJsonModule | Allows importing .json files |
allowImportingTsExtensions | Allows .ts/.tsx in import specifiers |
resolvePackageJsonExports | Honors package.json exports field |
resolvePackageJsonImports | Honors package.json imports field |
customConditions | Additional conditions for exports/imports resolution |
noResolve | Disables automatic file inclusion via resolution |
Sources: src/compiler/commandLineParser.ts150-500 src/compiler/moduleNameResolver.ts100-300
Required Information
tsc --versiontsconfig.json — all fields, especially compilerOptions, include, exclude, and referencesTS2307)node_modules and package.json filespackage.json files, including main, module, types, typings, and exports fields.d.ts content or note that no .d.ts existsOptional but Often Useful
tsc --traceResolution (see below)@typescript/native-preview (typescript-go)--traceResolutionRunning tsc --traceResolution 2>&1 | grep <module-name> produces a log of every file path TypeScript probes for a given specifier. This trace corresponds to the failedLookupLocations field of ResolvedModuleWithFailedLookupLocations in the internal representation.
What --traceResolution reveals:
Include the relevant section of --traceResolution output in the bug report when the error is unclear.
Sources: src/compiler/moduleNameResolver.ts100-400 src/compiler/types.ts1-100
A minimal reproduction is the single most effective way to get a module resolution bug fixed quickly.
Preferred formats (in order of preference):
moduleResolution and module options setpackage.json, tsconfig.json, and minimal source files that reproduce the issue when tsc is runChecklist for a valid repro:
tsc in the repro directory produces the reported errornode_modules directory is NOT committed; a package.json with devDependencies is sufficient.d.ts stub that reproduces the structureSome situations look like module resolution bugs but are actually expected behavior. Understanding these prevents misfiled issues.
| Symptom | Likely Cause | Not a Bug If… |
|---|---|---|
TS2307 for a .js import under node16 | Missing .js extension in specifier | moduleResolution: node16 requires explicit extensions per the Node.js ESM spec |
TS7016 for a CJS package | No @types/… package available | The package intentionally ships without types; file a DefinitelyTyped PR instead |
TS2305 for a deep import | package.json exports field blocks the path | The package author restricted the exported paths; this is by design |
| Default import error | esModuleInterop: false and CJS package | Enable esModuleInterop or use import * as X syntax |
Resolution works in editor but not tsc | Language service uses different tsconfig.json | Verify the tsconfig.json the editor is using with tsserver logging |
Sources: src/compiler/diagnosticMessages.json1-100 src/compiler/moduleNameResolver.ts100-500
When triaging a module resolution bug, the relevant code path in the TypeScript compiler is:
Sources: src/compiler/program.ts270-325 src/compiler/moduleNameResolver.ts100-250 src/compiler/resolutionCache.ts1-100
The ResolutionCache in src/compiler/resolutionCache.ts is used by tsserver (see 5.2) to avoid re-resolving unchanged modules on file edits. A resolution bug that appears only in watch mode or the language server (but not in a fresh tsc invocation) should mention this in the report, as it may involve cache invalidation logic rather than the core resolution algorithm.
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.