TypeScript never Type: Exhaustive Checks and never vs void

never is the type with no values. A function whose return type is never never returns normally: it throws or runs forever. A variable of type never marks code that cannot run, which is what makes exhaustive checks possible.

function fail(message: string): never {
  throw new Error(message);
}

function parsePort(text: string): number {
  const n = Number(text);
  if (Number.isInteger(n) && n > 0 && n < 65536) return n;
  return fail(`invalid port: ${text}`); // never is assignable to number
}

console.log(parsePort("8080")); // 8080

try {
  parsePort("http");
} catch (e) {
  console.log((e as Error).message); // invalid port: http
}

return fail(...) compiles in a function that returns number because never is assignable to every type: a value of type never can never actually arrive.

Functions That Never Return

Two kinds of function never reach their end: one that always throws, and one with an infinite loop. The compiler checks the claim. A function annotated never whose end is reachable is error TS2534, A function returning 'never' cannot have a reachable end point.

function fail(message: string): never {
  throw new Error(message);
}

function runForever(): never {
  while (true) {
    // poll, serve requests...
  }
}

Inference differs by syntax. A function declaration that only throws is inferred as returning void, while an arrow function or function expression that only throws is inferred as never:

function f1() { throw new Error("x"); }       // () => void
const f2 = () => { throw new Error("x"); };   // () => never

Narrowing only treats a call as a dead end when the called name has an explicit type that returns never: a function declaration annotated : never, like fail above, or a variable with a type annotation, const fail: (m: string) => never = (m) => { throw new Error(m); }. An inferred never does not count, and neither does const fail = (m: string): never => ..., where only the arrow is annotated and the variable is not.

never vs void

The practical difference shows in narrowing. After if (!user) fail("no user"), the compiler knows user is defined on the next line only if fail returns never. With a void return it assumes execution can continue.

Exhaustive Checks with never

Each case of a switch over a union narrows the value. When every member has been handled, what is left in default is never. Assigning it to a never variable turns "I handled every case" into something the compiler verifies:

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.side ** 2;
    default: {
      const unhandled: never = shape; // shape is never here
      throw new Error(`unknown shape: ${JSON.stringify(unhandled)}`);
    }
  }
}

console.log(area({ kind: "square", side: 3 })); // 9
console.log(area({ kind: "circle", radius: 1 }).toFixed(4)); // 3.1416

Now add a third member to the union without adding a case:

// This does not compile: "triangle" is not handled
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number }
  | { kind: "triangle"; base: number; height: number };

function assertNever(value: never): never {
  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);
}

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.side ** 2;
    default:
      return assertNever(shape);
  }
}

console.log(area({ kind: "square", side: 3 }));

index.ts(18,26): error TS2345: Argument of type '{ kind: "triangle"; base: number; height: number; }' is not assignable to parameter of type 'never'.

The error names the member you forgot. Add case "triangle": return (shape.base * shape.height) / 2; and it compiles again. The assertNever helper is the reusable form of the same check, and its throw still matters at runtime: data from JSON or an older client can contain a kind the types say is impossible. This pattern is the backbone of discriminated unions.

Narrowing Down to never

The same thing happens with any narrowing, not only switch. Once every possibility is ruled out, the variable has type never:

function describe(x: string | number | boolean): string {
  if (typeof x === "string") return `string "${x}"`;
  if (typeof x === "number") return `number ${x}`;
  if (typeof x === "boolean") return `boolean ${x}`;
  const nothing: never = x; // every option handled
  return nothing;
}

console.log(describe("a")); // string "a"
console.log(describe(2));   // number 2
console.log(describe(true)); // boolean true

If you later widen the parameter to string | number | boolean | bigint, the const nothing: never = x line becomes an error, pointing at the function that needs updating.

never Disappears in Unions

never is the empty set of values, so adding it to a union changes nothing: string | never is just string. That is how conditional types filter unions. A branch that returns never removes that member:

type OnlyStrings<T> = T extends string ? T : never;

type Mixed = "a" | "b" | 1 | 2 | true;
type Letters = OnlyStrings<Mixed>; // "a" | "b"

const ok: Letters = "a";
// @ts-expect-error: Type '1' is not assignable to type 'Letters'.
const bad: Letters = 1;

console.log(ok);

The built-in Exclude<T, U> and Extract<T, U> work exactly this way. In an intersection it is the opposite: string & never is never.

Impossible Types Become never

An intersection that no value can satisfy reduces to never:

type A = string & number;                   // never
type B = { kind: "a" } & { kind: "b" };     // never

Reading a property of a B value reports the reason: Property 'kind' does not exist on type 'never'. The intersection 'B' was reduced to 'never' because property 'kind' has conflicting types in some constituents. When a type you built turns out to be never, look for two parts that contradict each other.

never, unknown and any

unknown is the top of the type hierarchy and never is the bottom. any is not part of the hierarchy at all: it switches the checks off.