Fix TS2304: Cannot Find Name 'X'

What This Error Means

TypeScript error TS2304 means the compiler encountered a name — a variable, function, class, type, or interface — that it does not recognize in the current scope. TypeScript has looked through all available declarations, imports, and ambient type definitions, and cannot find anything matching that name.

This is one of the most common TypeScript errors, and it almost always points to one of a few straightforward issues: a missing import, a typo, or a missing type definition package.

Common Causes

1. Missing import statement

You are using something from another module but forgot to import it.

// ❌ Error: Cannot find name 'z'. (TS2304)
const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
})

// ✅ Import the module
import { z } from 'zod'
 
const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
})

2. Typo in the name

A simple spelling mistake can trigger TS2304. TypeScript's related error TS2552 ("Did you mean...?") sometimes catches near-misses, but exact mismatches land on TS2304.

// ❌ Error: Cannot find name 'docuemnt'. (TS2304)
const heading = docuemnt.querySelector('h1')

// ✅ Fix the typo
const heading = document.querySelector('h1')

3. Missing type definitions for browser or Node.js APIs

If your tsconfig.json does not include the right lib entries, global APIs will not be recognized.

// ❌ Error: Cannot find name 'fetch'. (TS2304)
// This happens when "dom" is missing from tsconfig lib
const response = await fetch('/api/users')

// ✅ Add the required lib entries in tsconfig.json
{
  "compilerOptions": {
    "lib": ["es2020", "dom", "dom.iterable"]
  }
}

For Node.js globals like process or Buffer, install the Node type definitions:

npm install --save-dev @types/node

4. Missing @types package for a third-party library

Some npm packages do not ship their own type definitions. You need to install the community-maintained types separately.

// ❌ Error: Cannot find name 'describe'. (TS2304)
// Happens when @types/jest or @types/mocha is not installed
describe('UserService', () => {
  it('should create a user', () => {
    // ...
  })
})

# ✅ Install the type definitions
npm install --save-dev @types/jest

How to Fix It

1. Check for typos — read the error message carefully. The name in quotes is exactly what TypeScript is looking for. Make sure it matches the declaration exactly, including capitalization.

2. Add the missing import — if the name comes from another module or package, add an import statement at the top of your file.

3. Install type definitions — for third-party libraries, check if an @types/ package exists:

   npm install --save-dev @types/library-name

4. Check your tsconfig lib setting — for browser APIs (document, window, fetch), make sure "dom" is in your lib array. For modern JavaScript features (Promise, Map, Set), include "es2020" or later.

5. Check the scope — make sure the variable or type is declared in a scope that is accessible from where you are using it. A variable declared inside a function is not available outside it.

6. Declare ambient types — if you are working with global variables injected at runtime (like environment variables or third-party scripts), declare them in a .d.ts file:

// global.d.ts
declare const __APP_VERSION__: string

FAQ

What causes TypeScript error TS2304?

TS2304 occurs when TypeScript encounters a name that has not been declared or imported in the current scope. The most common triggers are missing import statements, typos in variable or type names, and missing type definition packages (@types/*). TypeScript is telling you that it has no idea what this name refers to.

How do I fix "cannot find name" in TypeScript?

Start by checking for typos. If the spelling is correct, add the appropriate import statement. If the name is a global API (like document or process), check your tsconfig.json lib setting or install the relevant @types package. For custom global variables, create an ambient declaration in a .d.ts file that is included in your project.

Why do I get TS2304 for browser APIs?

Browser APIs like document, window, fetch, and localStorage require the "dom" lib to be included in your tsconfig.json. By default, TypeScript only knows about core JavaScript — you need to tell it that browser globals exist by adding "dom" and "dom.iterable" to the lib array in compilerOptions. If you are running in Node.js, these APIs genuinely do not exist, so the error is correct.