阅读中文版本

TypeScript TS2304 — Cannot Find Name

Fix TS2304 by correcting the identifier, importing the missing symbol, or declaring globals and library types in the tsconfig.

npx tsc --noEmit 2>&1 | grep TS2304

grep -n '"types"\|"lib"' tsconfig.json

Symptoms

This guide profiles the failure behind “TypeScript TS2304 — Cannot Find Name”. It walks through the observable symptoms, a reproducible diagnosis path, the underlying root cause, the concrete fix, and how to verify the change and prevent a regression.

Observed symptoms include:

• error TS2304: Cannot find name ‘process’ (or Buffer, describe)
• Editor shows red squiggles but the build sometimes passes
• The name is available at runtime yet unknown to TypeScript

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Reproduce and read the name

npx tsc --noEmit 2>&1 | grep TS2304

The missing name tells you whether to import it or add its ambient types.

Step 2: Check which types are configured

grep -n '"types"\|"lib"' tsconfig.json

A missing “types”: [“node”, “jest”] entry explains why Node/test globals are unknown.

Likely contributors, in order of frequency:

• The symbol is not imported into the file
• A global type (Node or test globals) is missing from the types option
• A typo or wrong case in the identifier

Root Cause

TypeScript resolves names from local declarations, imports, and configured ambient type packages. A name that exists only at runtime or in an unconfigured package is unknown to the type checker and reported as TS2304.

The Fix

Add the import for local symbols, add the relevant @types package and list it in compilerOptions.types, or declare a global with a d.ts file for genuinely global runtime values.

Watch out: Declaring a global that does not exist suppresses the error without providing the value; only declare real globals.

// local symbol must be imported
import { describe, it, expect } from 'vitest';
import { Buffer } from 'node:buffer';

// tsconfig.json
{
  "compilerOptions": {
    "types": ["node", "vitest/globals"]
  }
}

// ambient global for a runtime-provided value
// globals.d.ts
declare const __APP_VERSION__: string;

Verify and Prevent

Run tsc –noEmit and confirm TS2304 is gone; ensure runtime still has the symbol via a smoke test.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.