TypeScript "TS2304: Cannot find name" - Fix Missing lib/Globals

By Daniel Zoghalchali·Latchkey

tsc met an identifier it has no declaration for. Either the name was never imported, it is a global from a lib/types package that is not included, or it is simply misspelled. Unlike TS2307 (a missing module), TS2304 is a missing *name*.

What this error means

Type-checking fails with error TS2304: Cannot find name '<x>', naming the identifier - a missing import (useState), a DOM global (document, fetch) absent from lib, or a typo.

src/widget.ts:4:18 - error TS2304: Cannot find name 'document'.

4   const el = document.getElementById('app')
                 ~~~~~~~~

Diagnose it: which tsconfig and which compiler?

A TypeScript error that appears only in CI usually means the runner is compiling with a different config or a different compiler version than your editor. Your editor uses the workspace TypeScript and the nearest tsconfig.json; CI uses whatever the lockfile resolved and whatever config the build script names.

# what CI will actually use
npx tsc --version
npx tsc --showConfig | head -40

# which files are in the program (a missing include is a common cause)
npx tsc --listFiles | wc -l

# type-check only, no emit, same as most CI gates
npx tsc --noEmit

Common causes

Missing import for the name

A value/type used without importing it (e.g. useState without import { useState } from 'react') is an unknown name.

DOM/global lib not included

Browser globals like document, window, and fetch require "lib": ["DOM"]. A config with only ["ES2022"] omits them, so the name is unknown.

Missing @types for an ambient global

A global provided by a types package (e.g. test globals, Node globals) is unknown until that @types/* package is installed and included.

How to fix it

Import the name or include the lib

Add the missing import, or include the lib that provides the global.

// tsconfig.json - include DOM for browser globals
{ "compilerOptions": { "lib": ["ES2022", "DOM", "DOM.Iterable"] } }

Install the types for ambient globals

For globals from a types package, install and include it.

npm install -D @types/node
# then ensure it's included (auto, or list it in compilerOptions.types)

Pin the compiler so unrelated updates cannot break the gate

TypeScript adds errors in minor releases. An unpinned compiler turns a routine dependency update into a red build on code nobody touched, which is the most common false alarm in a TypeScript CI pipeline.

// package.json
{
  "devDependencies": {
    "typescript": "5.6.3"   // exact, not ^5.6.3
  }
}

How to prevent it

• Include DOM in lib for browser code that uses DOM globals.
• Install @types/* for any ambient globals you rely on.
• Run tsc --noEmit in CI so missing names fail before build.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation