JS with Types Start

TypeScript error

TS2304: A name the checker cannot find

  • Error TS2304
  • Tested with TypeScript 5.9

error TS2304: Cannot find name 'gtag'. is reported when code uses a name that is not declared anywhere the checker can see: not in the file, not imported, not a global from the libraries the config loads. When a declared name is close in spelling, the checker reports TS2552 with a suggestion instead.

In a JavaScript project the name usually exists at run time but comes from outside the code: an analytics or map library loaded with a <script> tag, a constant a bundler substitutes (__APP_VERSION__), or a global from a runtime whose types are not installed.

At a glance

CodeTS2304
MessageCannot find name '{0}'.
TypeScript's categoryerror
Listed underUnknown names and members
Turned on by No option: every checked file reports it
In .js files Reported when the file is checked: checkJs in jsconfig.json, or // @ts-check at the top of the file

The message is TypeScript's own text from its diagnostic messages file (Apache-2.0); {0} is filled in by tsc for each error.

What it looks like

analytics.js Error confirmed 5.9.3 TypeScript 5.9.3, run 21 October 2026: analytics.js(3,3): error TS2304: Cannot find name 'gtag'. analytics.js(7,24): error TS2304: Cannot find name '__APP_VERSION__'. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. analytics.js(3,3): error TS2304: Cannot find name 'gtag'. analytics.js(7,24): error TS2304: Cannot find name '__APP_VERSION__'. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. analytics.js(3,3): error TS2304: Cannot find name 'gtag'. analytics.js(7,24): error TS2304: Cannot find name '__APP_VERSION__'. checked 21 October 2026 
export function trackCheckout() {
  gtag("event", "begin_checkout");error TS2304: Cannot find name 'gtag'.
}

export const version = __APP_VERSION__;error TS2304: Cannot find name '__APP_VERSION__'.
Globals that a script tag or a bundler provides.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js"]
}

What causes it

  • A page script or a bundler provides the global, and nothing tells the checker it exists.
  • The global belongs to a runtime or library whose types the config does not load. For Node.js names such as process and Buffer the checker says so with TS2580 or TS2591, and for console and document with TS2584.
  • The name is defined in a file that is not part of the program (outside include).

How to fix it

Declare the globals in a .d.ts file

Create a file such as globals.d.ts with a declare line for each global, typed as precisely as you like, and make sure include matches it. A declaration file holds types only, so it adds nothing to your JavaScript at run time.

analytics.js TypeScript 5.9.3 TypeScript 5.9.3, run 21 October 2026: No errors. 6.0.3 TypeScript 6.0.3, run 21 October 2026: the same as 5.9.3. No errors. 7.0.2 TypeScript 7.0.2, run 21 October 2026: the same as 5.9.3. No errors. checked 21 October 2026 
export function trackCheckout() {
  gtag("event", "begin_checkout");
}

export const version = __APP_VERSION__;
Declare the globals once in a .d.ts file the config includes.
jsconfig.json for this example 
{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
    "strict": true,
    "target": "es2022",
    "module": "nodenext",
    "types": []
  },
  "include": ["*.js", "*.d.ts"]
}

Or install the library's types

If the global comes from a library with published types, install them (for example @types/google.maps) and, if your config has a types list, add the package to it. For a few well-known libraries the checker suggests the package itself: $ without jQuery's types is reported as TS2581 (TS2592 when the config has a types list), and both name @types/jquery.

A JSDoc-only alternative

If you would rather not add a .d.ts file, read the global through globalThis or window with a cast: const gtag = /** @type {(...args: unknown[]) => void} */ (/** @type {any} */ (window).gtag);. It works, but it has to be repeated in every file, which is why the declaration file is the usual answer.

Gotchas

  • A .d.ts file only counts when the program includes it. With "include": ["src/**/*.js"] a src/globals.d.ts is not matched; add "src/**/*.d.ts" or list the file.
  • With skipLibCheck on (the jsconfig.json default), mistakes inside your own .d.ts files are not reported, so keep the declarations simple.

  • TypeScript error

    TS2552: A misspelled name, with a suggestion

    TS2552 means a variable or function name is not declared but a similar one is. Usually a case or spelling slip: use the suggested name.

  • TypeScript error

    TS2339: A property the type does not have

    TS2339 means code reads a property its type does not declare: window.dataLayer, a field added later, a typo with no close match. Declare it or type the object.

  • TypeScript error

    TS2584: console is missing because lib leaves out the DOM

    TS2584 means console or document is unknown: lib lists only ECMAScript libraries and no Node.js types are loaded. Add @types/node or the dom library.

  • jsconfig.json key

    include

    include lists the files and folders the checker starts from, as globs relative to jsconfig.json. A folder name picks up every .js file under it.

  • jsconfig.json option

    skipLibCheck

    skipLibCheck skips checking every .d.ts file, your own included. A jsconfig.json turns it on by default, which can hide a typo in a .d.ts you wrote.

  • jsconfig.json option

    types and typeRoots

    types lists the @types packages whose globals the checker loads, like node for process. Without it, TypeScript 5.9 loads every @types package; 6.0 loads none.

Sources

Last reviewed 20 October 2026.