How to Fix "Cannot find name" and Other Missing Type Errors in TypeScript

Overview

Here is the short version: when TypeScript says it cannot find a name or type, the problem is usually one of five things. Either the symbol is not declared, the right library types are not loaded, the package types are missing, the file is outside your TypeScript project, or your config points TypeScript at the wrong environment.

That means the most reliable fix is not to patch the error message line-by-line. It is to identify which layer is responsible:

• Your code: a variable, function, import, or type alias does not exist in scope.
• Your runtime environment: you are using browser globals in Node, or Node globals in the browser.
• Your installed packages: the package has no bundled types and you have not installed separate type definitions.
• Your TypeScript config: lib, types, include, exclude, baseUrl, or paths is misaligned.
• Your tooling: the editor, test runner, or build tool is reading a different config than the compiler.

A few examples of this error family:

• Cannot find name 'window'
• Cannot find name 'process'
• Cannot find name 'describe'
• Cannot find module 'some-package' or its corresponding type declarations
• Cannot find type definition file for 'node'

Before changing code, run this basic triage:

1. Read the exact symbol TypeScript cannot find.
2. Decide whether it should come from your file, a package, the browser, Node.js, or a test framework.
3. Open the active tsconfig.json for that file.
4. Check whether the file is included in the project.
5. Check whether the environment types are installed and loaded.

If you want a deeper configuration baseline, the site’s guide to tsconfig.json best settings by project type is a useful companion to this checklist. For broader diagnosis patterns, keep the TypeScript error codes list nearby as well.

Checklist by scenario

Use this section like a decision tree. Start with the scenario that matches the missing name or missing type.

1. The missing name is a browser global like window, document, or fetch

What this usually means: your project is not loading DOM library types, or you are writing code in a non-browser context.

Checklist:

• Open tsconfig.json and inspect compilerOptions.lib.
• If lib is explicitly set, make sure it includes browser libraries such as DOM and a matching ECMAScript target like ES2022.
• If you are in a Node-only project, do not add DOM types just to silence the error unless the code truly runs in the browser.
• If the file is shared across environments, split runtime-specific code or guard access with environment-aware abstractions.

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM"]
  }
}

If you are building a frontend project, it may be worth comparing your setup with a known-good stack in this React + TypeScript setup guide.

2. The missing name is a Node global like process, Buffer, or __dirname

What this usually means: Node type definitions are not installed or not loaded into the project.

Checklist:

• Install Node types if your project needs them: npm i -D @types/node.
• Check whether compilerOptions.types exists. If it does, TypeScript loads only the listed type packages.
• If you use types, add node to the array.
• Make sure the file actually belongs to your backend TypeScript project, not a frontend package in a monorepo.

{
  "compilerOptions": {
    "types": ["node"]
  }
}

This is one of the most common causes of Cannot find name 'process' in a node typescript setup. If your backend setup feels fragile, the article Node.js + TypeScript Setup That Still Works in 2026 can help you compare structure and config choices.

3. The missing name comes from a test framework like describe, it, expect, or jest

What this usually means: your test framework types are not installed, or the test files use a different config than your application files.

Checklist:

• Install the relevant types package if needed, such as @types/jest or test-runner-specific packages.
• If your test runner provides its own types, follow that package’s setup rather than adding unrelated ambient types.
• Add the framework to compilerOptions.types if you restrict types manually.
• Check whether tests use a dedicated tsconfig like tsconfig.test.json.
• Make sure your editor is reading the test config for those files.

Tests often fail type resolution because the app config intentionally excludes **/*.test.ts or uses a separate include pattern.

4. The error says Cannot find module or Cannot find type definition file

What this usually means: either the package is missing, the package types are missing, or TypeScript cannot resolve the import path.

Checklist:

• Confirm the package is installed in the correct workspace or package directory.
• Check whether the import path matches the package name and export path exactly.
• If the package does not bundle its own types, install the matching @types/... package if one exists.
• Inspect your package version. Some packages bundle types in newer versions but relied on @types in older ones.
• Check moduleResolution, baseUrl, and paths in tsconfig.json.
• In ESM projects, verify the package exports support your import style.

Example:

import express from 'express';
// If TypeScript cannot find express types:
// 1) ensure express is installed
// 2) install @types/express if required
// 3) verify your project and editor use the same tsconfig

When TypeScript is not finding types for path aliases, the issue is often not the alias itself but a mismatch between the compiler, bundler, and test runner. A path that works in Vite or Next.js may still fail in plain tsc if the alias is only defined in one tool.

5. The missing name is your own type or variable

What this usually means: the symbol is out of scope, not exported, or imported incorrectly.

Checklist:

• Make sure the symbol is declared before use if you are not importing it.
• Check spelling and case. TypeScript import paths and symbol names can be case-sensitive depending on the platform and tooling.
• Confirm the source file exports the symbol.
• Use the correct import form: named export vs default export.
• Check for circular imports that break assumptions about available symbols.

// types.ts
export type User = { id: string };

// app.ts
import type { User } from './types';

const currentUser: User = { id: '1' };

This is the simplest class of error, but it is also easy to miss in large codebases during a JavaScript to TypeScript migration.

6. The project is a mixed JavaScript and TypeScript codebase

What this usually means: TypeScript is trying to understand files without declarations, or JavaScript modules are imported without enough type information.

Checklist:

• Check whether allowJs and checkJs are enabled.
• If JavaScript files are part of the build, consider adding JSDoc types where useful.
• Add declaration files for untyped internal modules if needed.
• For third-party JavaScript packages without types, create a minimal .d.ts file as a temporary bridge.

// declarations.d.ts
declare module 'legacy-utility' {
  export function parse(input: string): unknown;
}

This is often the least elegant fix, but it can be the right transitional step in a migration.

7. The error appears only in the editor, not in the CLI

What this usually means: your editor is using a different TypeScript version, a different project root, or stale language service state.

Checklist:

• Restart the TypeScript server in your editor.
• Make sure the workspace opens at the correct repository root.
• Check whether the editor uses the workspace TypeScript version instead of a bundled version.
• Run tsc --noEmit from the project root to compare results.
• Inspect monorepo boundaries. The editor may attach the file to the wrong nearest tsconfig.json.

When CLI and editor disagree, trust the compiler first, then fix the editor context.

What to double-check

If the scenario checklist did not solve the problem, work through these configuration checks carefully. These are the settings that most often explain why TypeScript is missing types.

include, exclude, and file location

A file outside the active project can show misleading type errors. Confirm the file is included by the intended config. In monorepos, a file may live inside one package but be picked up by another config or by none at all.

types

This option is easy to overlook. If you define it, TypeScript stops auto-including other available type packages and only loads the ones listed. That is useful for controlling globals, but it also causes missing types if you forget node, jest, or other environment packages.

lib

If you define lib, you replace the default set. A browser project that explicitly sets only ES2022 will not know about window or document. A backend project generally should not pull in DOM globals unless there is a good reason.

baseUrl and paths

Path aliases are convenient, but they create another layer that can break. Make sure the alias matches your folder structure exactly and is mirrored where needed in your bundler or test runner.

typeRoots

This setting is less common, but it can hide types unexpectedly. If you define typeRoots, TypeScript will look only in those directories for type packages. If your installed types live elsewhere, they will not be found.

Declaration files

Check whether a local global.d.ts or env.d.ts exists but is excluded from the project. Many missing-name issues around custom globals are simply declaration files that are not included.

Module system mismatches

If you are mixing CommonJS, ESM, and framework-specific conventions, import resolution may fail in ways that surface as missing types. Be careful with default imports, synthetic defaults, package export maps, and extension-based imports.

Common mistakes

This is the short list of fixes that look right but usually create a second problem later.

• Adding any everywhere. This suppresses useful feedback and hides the real configuration issue.
• Installing random @types packages without checking whether the package already bundles types. This can create version mismatches.
• Adding DOM types to a Node project just to make fetch or window compile. That can pollute globals and blur runtime boundaries.
• Forgetting that types is restrictive. Once it exists, missing environment types become much more likely.
• Using a declaration file that is never included. A perfect .d.ts file does nothing if TypeScript never reads it.
• Assuming the editor reflects the build. Editors cache aggressively and may attach a file to the wrong project.
• Ignoring monorepo package boundaries. A dependency or type package installed in one workspace may not be available in another.
• Confusing framework magic with TypeScript defaults. Some frameworks inject types or config conventions that do not apply outside that tool.

A good habit is to make the smallest change that explains the error. If the fix requires three unrelated config edits, stop and verify your assumptions. TypeScript missing types are usually traceable to one clear mismatch.

When to revisit

This topic is worth revisiting whenever your environment changes, because missing type errors tend to appear at boundaries you just moved. Use this quick action list before or after major project changes:

• After adding a new runtime context: browser code in a backend repo, server code in a frontend app, worker code, or test utilities.
• After introducing a new framework or bundler: especially when moving to a different module system or alias strategy.
• After changing tsconfig.json: particularly lib, types, typeRoots, include, exclude, and path mapping.
• After upgrading dependencies: packages sometimes add bundled types, remove legacy definitions, or change exports.
• During JavaScript to TypeScript migration: each new typed boundary can expose missing declarations.
• When splitting a monorepo into packages: type visibility changes quickly when configs and package roots multiply.

For a practical maintenance routine, keep this five-step review process:

1. Run tsc --noEmit in CI and locally before larger merges.
2. Document the intended environment for each package: browser, Node, tests, or shared.
3. Keep tsconfig files small and purposeful rather than overloaded with copied settings.
4. Prefer explicit environment boundaries over one config that tries to satisfy every runtime.
5. When a missing type error appears, classify it first: scope, environment, package, config, or tooling.

That classification step is what turns this from a frustrating error family into a repeatable troubleshooting process. If TypeScript cannot find a name, there is almost always a concrete place to look next. The goal is not to memorize every error string. It is to know which layer owns the missing type and to verify that layer deliberately.