Module Resolution Issues

Relevant source files

• src/compiler/binder.ts
• src/compiler/checker.ts
• src/compiler/commandLineParser.ts
• src/compiler/core.ts
• src/compiler/diagnosticMessages.json
• src/compiler/emitter.ts
• src/compiler/moduleNameResolver.ts
• src/compiler/moduleSpecifiers.ts
• src/compiler/parser.ts
• src/compiler/program.ts
• src/compiler/resolutionCache.ts
• src/compiler/scanner.ts
• src/compiler/sys.ts
• src/compiler/types.ts
• src/compiler/utilities.ts
• src/harness/client.ts
• src/harness/fourslashImpl.ts
• src/harness/fourslashInterfaceImpl.ts
• src/harness/harnessLanguageService.ts
• src/server/editorServices.ts
• src/server/project.ts
• src/server/protocol.ts
• src/server/scriptInfo.ts
• src/server/scriptVersionCache.ts
• src/server/session.ts
• src/server/utilities.ts
• src/services/codefixes/importFixes.ts
• src/services/completions.ts
• src/services/exportInfoMap.ts
• src/services/findAllReferences.ts
• src/services/goToDefinition.ts
• src/services/importTracker.ts
• src/services/services.ts
• src/services/types.ts
• src/services/utilities.ts
• src/testRunner/unittests/moduleResolution.ts
• src/testRunner/unittests/reuseProgramStructure.ts
• src/testRunner/unittests/tsserver/exportMapCache.ts
• tests/baselines/reference/api/typescript.d.ts
• tests/baselines/reference/declarationEmitHasTypesRefOnNamespaceUse.js
• tests/baselines/reference/symbolLinkDeclarationEmitModuleNames.errors.txt
• tests/baselines/reference/symbolLinkDeclarationEmitModuleNames.js
• tests/baselines/reference/symbolLinkDeclarationEmitModuleNames.types
• tests/baselines/reference/symbolLinkDeclarationEmitModuleNamesImportRef.js
• tests/baselines/reference/symbolLinkDeclarationEmitModuleNamesImportRef.symbols
• tests/baselines/reference/symbolLinkDeclarationEmitModuleNamesImportRef.types
• tests/baselines/reference/symbolLinkDeclarationEmitModuleNamesRootDir.js
• tests/baselines/reference/symbolLinkDeclarationEmitModuleNamesRootDir.symbols
• tests/baselines/reference/symbolLinkDeclarationEmitModuleNamesRootDir.types
• tests/baselines/reference/tsserver/exportMapCache/invalidates-the-cache-when-a-file-is-opened-with-different-contents.js
• tests/cases/compiler/symbolLinkDeclarationEmitModuleNames.ts
• tests/cases/compiler/symbolLinkDeclarationEmitModuleNamesRootDir.ts
• tests/cases/fourslash/fourslash.ts
• tests/cases/fourslash/server/completionsOverridingMethodCrash2.ts

This page documents how to debug and report module resolution issues in TypeScript. Module resolution determines how TypeScript locates and loads modules when processing import statements. When resolution fails or behaves unexpectedly, specific debugging techniques and information are required to identify the root cause.

For information about how module resolution works internally in the compiler, see Compiler Architecture. For Language Service features related to imports, see Organize Imports.

Overview of Module Resolution Problems

Module resolution issues manifest in several distinct ways, each requiring different diagnostic approaches. TypeScript's module resolution must align with the runtime module loader (Node.js, bundlers, browsers) to ensure that code that compiles successfully will also execute correctly.

Sources: src/compiler/diagnosticMessages.json (Error codes 2307 "Cannot find module", 6053), src/compiler/moduleNameResolver.ts

Module Resolution Debugging Workflow

The following workflow provides a systematic approach to diagnosing module resolution issues:

Sources: src/compiler/program.ts:205-206 (Implementation of isTraceEnabled), src/compiler/moduleNameResolver.ts

Essential Debugging Commands

TypeScript provides two critical command-line flags for debugging module resolution:

--traceResolution

The --traceResolution flag outputs detailed information about the module resolution process for each import statement. This trace is triggered when isTraceEnabled(options, host) returns true src/compiler/program.ts205-206 The output is handled by the ModuleResolutionHost or the internal tracing infrastructure.

Example usage:

The output will include entries like:

======== Resolving module './foo' from '/path/to/project/index.ts'. ========
Module resolution kind is not specified, using 'NodeJs'.
Loading module as file / folder, candidate module location '/path/to/project/foo', target file type 'TypeScript'.
File '/path/to/project/foo.ts' exist - use it as a name resolution result.
======== Module name './foo' was successfully resolved to '/path/to/project/foo.ts'. ========

--showConfig

The --showConfig flag displays the effective compiler configuration after all tsconfig.json files have been merged and defaults applied. This is handled by parseJsonSourceFileConfigFileContent src/compiler/program.ts250

Example usage:

This outputs the complete CompilerOptions src/compiler/types.ts90 including:

• moduleResolution strategy src/compiler/program.ts226
• baseUrl and paths mappings
• rootDirs configuration
• typeRoots and types settings

Sources: src/compiler/program.ts:205-250(), src/compiler/types.ts:90()

Required Information for Bug Reports

Valid module resolution bug reports must include essential components that allow the team to recreate the Program src/compiler/program.ts264 state.

1. Demo Repository

A cloneable Git repository that reproduces the issue is mandatory. The repository must:

• Use tsc directly (not third-party build tools).
• Include package.json with dependencies.
• Include complete tsconfig.json configuration.
• Contain minimal reproduction code.

2. Module Resolution Defect Type

Defect Type	Description
Build-time failure	Module resolves at runtime but tsc cannot find it.
False positive	tsc compiles successfully but fails at runtime.
Wrong file	Module resolves to an incorrect file path.
Wrong types	Module resolves to correct file but .d.ts definitions are incorrect.

3. Package.json Files

Both the importing and target package.json files are required. The compiler uses PackageJsonInfo src/compiler/types.ts13 and PackageJsonInfoCache src/compiler/types.ts14 to resolve conditional exports and imports.

Key fields:

• "type": Determines if a file is an ES module src/compiler/program.ts184
• "exports"/"imports": Checked if moduleResolutionSupportsPackageJsonExportsAndImports is true src/compiler/program.ts227

Sources: src/compiler/program.ts:184-227(), src/compiler/types.ts:13-14()

Internal Implementation of Resolution

Module resolution is orchestrated by the Program src/compiler/program.ts264 using the ModuleResolutionCache src/compiler/types.ts9

Sources: src/compiler/program.ts:264(), src/compiler/types.ts:9(), src/compiler/moduleNameResolver.ts

Common Module Resolution Misconfigurations

Incorrect moduleResolution Setting

The moduleResolution option src/compiler/program.ts226 defines the algorithm used:

• Classic: Legacy resolution.
• Node: Node.js resolution for CommonJS.
• Node16/NodeNext: Modern Node.js resolution supporting ESM/CJS dual packages.
• Bundler: Optimized for modern bundlers like Vite/Webpack.

Missing paths or baseUrl

Path mapping is defined in CompilerOptions src/compiler/types.ts90 The compiler uses findBestPatternMatch src/compiler/utilities.ts147 to map module specifiers to disk locations.

Sources: src/compiler/types.ts:90(), src/compiler/utilities.ts:147()

Diagnostic Output Examples

Example --traceResolution Output

The compiler produces trace logs when resolving imports. For example, when checking a SourceFile src/compiler/types.ts195 the resolver logs its attempts:

======== Resolving module 'pkg' from '/src/app.ts'. ========
Module resolution kind is not specified, using 'NodeNext'.
Resolving with primary search path '/src/node_modules'.
File '/src/node_modules/pkg/package.json' exists.
...
======== Module name 'pkg' was successfully resolved to '/src/node_modules/pkg/dist/index.d.ts'. ========

Sources: src/compiler/program.ts:205(), src/compiler/moduleNameResolver.ts

Issue Template Checklist

Before submitting a module resolution issue, verify:

• Tested with latest TypeScript version.
• Created minimal demo repository.
• Collected tsc --showConfig output.
• Collected tsc --traceResolution output.
• Verified the issue occurs with tsc directly.

Sources: src/compiler/program.ts:205-250()