TS2304: Cannot find name 'X'

The exact error string

const id = randomUUID();
// error TS2304: Cannot find name 'randomUUID'.

console.log(process.env.NODE_ENV);
// error TS2304: Cannot find name 'process'.

document.querySelector("#app");
// error TS2304: Cannot find name 'document'.

All three lines throw the same error code for genuinely different reasons: a missing import, a missing Node type package, and a missing DOM library. TS2304 is TypeScript telling you a single name has no declaration it can see — not a syntax problem and not a whole-module failure (that's TS2307). Diagnosing it well means asking one question first: what kind of name is this?

How to diagnose it (what kind of name is X?)

• A value/type you wrote in another file → missing import (Fix 1).
• process, require, __dirname, Buffer, module → Node globals, need @types/node (Fix 2).
• document, window, localStorage → browser/DOM globals, need the DOM lib (Fix 3). (fetch is different in Node — see Fix 3.)
• TypeScript says “Did you mean…?” → a typo or casing mistake (Fix 4).
• describe, it, expect, jest, vi → test-runner globals, need their types (Fix 5).
• You wrote a .d.ts declaring it yourself, but TS still can't see it → ambient declaration not picked up (Fix 6).

Fix 1: a missing import (the most common cause)

In application code, this is the overwhelming majority of TS2304 errors. You referenced something exported by another module but never imported it:

// ❌ randomUUID is never imported
const id = randomUUID();

// ✅ import it from the module that exports it
import { randomUUID } from "crypto";
const id = randomUUID();

Your editor almost always offers a lightbulb quick-fix (“Add import from…”) — accept it and move on. When the auto-import doesn't appear, it usually means the exporting module itself can't be resolved, which is a TS2307 problem hiding underneath; fix that first and the import suggestion returns.

Fix 2: Node globals (process, require, Buffer, __dirname)

These identifiers exist at runtime in Node, but TypeScript ships no types for them by default. Install the Node type definitions:

npm install --save-dev @types/node

Then make sure your tsconfig.json actually loads them. If you set compilerOptions.types at all, it becomes an allow-list — anything not listed is excluded, including @types/node:

{
  "compilerOptions": {
    "types": ["node"]   // ✅ if you list types at all, include "node"
    // omitting "types" entirely also works — then ALL @types packages load
  }
}

Fix 3: browser/DOM globals (document, window, fetch)

DOM globals get their types from TypeScript's built-in DOM library, which is included automatically unless you override lib. If you set lib manually and left DOM out, browser globals stop resolving:

{
  "compilerOptions": {
    "lib": ["ES2022", "DOM", "DOM.Iterable"]   // ✅ add "DOM" back
  }
}

For code that never touches the browser (a pure Node service), the correct move is the opposite — keep DOM out so a stray document reference is caught at compile time rather than crashing at runtime. fetch deserves a special note: it isn't strictly a DOM-only global anymore. Browsers provide it through the DOM lib, but Node 18+ ships fetch natively at runtime, and its types come from @types/node, not DOM. If fetch is undefined in a Node file, install/update @types/node (Fix 2) rather than adding DOM to lib — pulling in the full DOM lib for a Node project brings along browser types (like Window) that don't exist at runtime and can mask real bugs.

Fix 4: a typo or wrong casing

When TypeScript can find a nearby declaration with a similar name, it upgrades the message to TS2552 and suggests the fix:

const user = getUserByID(1);
getUserById(user);
// error TS2552: Cannot find name 'getUserById'. Did you mean 'getUserByID'?

That “Did you mean” line is the strongest possible hint — it's almost always a casing or spelling slip. Plain TS2304 with no suggestion points the other way: the name isn't declared anywhere nearby, so look at Fixes 1–3 instead.

Fix 5: test-runner and framework globals

Globals injected by a test runner (describe, it, expect, jest, vi, beforeEach) need their type packages installed and referenced:

# Jest
npm install --save-dev @types/jest

# Vitest — enable globals in the config instead of importing them everywhere
// vitest.config.ts
export default { test: { globals: true } }
// tsconfig.json
{ "compilerOptions": { "types": ["vitest/globals"] } }

A frequent trap here: a separate tsconfig for tests that forgets to include the test types, or a test file that falls outside the include glob of any tsconfig. If the tests run but the editor still flags the globals, the file simply isn't covered by a tsconfig that references the right types — add it to include.

Fix 6: your own ambient declaration isn't being picked up

This one is the most confusing to hit, because the declaration is sitting right there in your own codebase and TypeScript still won't recognize it. It happens when a custom .d.ts file declares a global, but the TypeScript program never actually parses that file:

// globals.d.ts
declare const API_URL: string;

// somewhere else in the project
console.log(API_URL);
// error TS2304: Cannot find name 'API_URL' — even though globals.d.ts declares it right there

Two separate things can cause this, and they need different fixes:

• The .d.ts file isn't covered by tsconfig.json's include (or is caught by exclude). TypeScript only looks at files reachable from include/files plus whatever those files import — a stray types/globals.d.ts outside that graph is silently never read. Add its path (or its containing folder) to include.
• The .d.ts file accidentally became a module. A declaration file with no top-level import or export is treated as a global script, and everything in it merges into global scope. The moment you add any top-level import/export to that same file, TypeScript treats it as a module instead, and its contents stop being global automatically. To declare globals from a module-shaped file, wrap them explicitly:

// globals.d.ts — this file has other imports, so it's a module, not a script
import type { SomeType } from "./types";

declare global {
  const API_URL: string;
  interface Window {
    myAppVersion: string;
  }
}

export {};   // required so the file is a module and declare global has an effect

The search terms that land here are usually “typescript cannot find name global variable”, “typescript declare global variable”, or “typescript global.d.ts not working” — if that's your situation, check include first, then check whether the file has an import/export without a matching declare global block.

Common variants of this message

Debugging checklist

• ✓ Is X defined in another file? Add the import (accept the editor's quick-fix)
• ✓ Is it a Node global? npm i -D @types/node, and include "node" if you set types
• ✓ Is it a browser global? Add "DOM" to compilerOptions.lib
• ✓ Does TypeScript say “Did you mean”? It's a typo — accept the suggestion
• ✓ Is it a test global? Install @types/jest / enable vitest/globals
• ✓ Is it fetch in a Node file? Update @types/node, not lib
• ✓ Declared it yourself in a .d.ts? Check tsconfig include, and whether the file needs declare global { } + export {}
• ✓ Editor-only, but the build works? Restart the TS server to clear a stale cache