Void and Never in TypeScript

Void and never in TypeScript both describe the absence of a value, but they mean very different things. void means a function finishes but you should not care about what it returns. never means a function never finishes at all, or that a particular code path is impossible to reach.

The table below captures the difference at a glance:

Void: A Function That Returns Nothing Useful

A function with a void return type finishes normally but does not produce a meaningful return value. It runs for its side effects, such as logging, updating the DOM, or writing to a database.

typescript

function logMessage(message: string): void {
  console.log(message);
  // No return statement
}

Calling this function runs it and produces undefined at runtime, but the void type tells callers not to rely on that value:

typescript

const result = logMessage("Hello");
// result is void, using it would be a mistake

void is also the type TypeScript infers automatically when a function has no return statement or only an empty return, so you rarely need to write it by hand for simple side-effect functions.

Void in Callbacks

void is common in callback types where you do not care what the callback returns:

typescript

type ClickHandler = (event: MouseEvent) => void;
 
const handleClick: ClickHandler = (event) => {
  console.log(event.clientX, event.clientY);
};

A void callback type has a special rule: the implementation is still allowed to return a value, and TypeScript will not complain, because the caller has already promised not to use it.

typescript

const handleClick: ClickHandler = (event) => {
  return event.clientX; // ok: void accepts any return value and discards it
};

This special rule applies only to void in callback positions. It exists so that array methods like forEach, which type their callback as void, can still accept arrow functions with an implicit expression body without a type error.

Void vs Undefined

A function annotated with : undefined behaves differently from one annotated : void. With undefined, the function must explicitly return that value:

typescript

function logVoid(message: string): void {
  console.log(message); // ok: no return needed
}

The undefined version requires an explicit return statement even when there is nothing meaningful to send back, which is the opposite of how the void version above behaves without one:

typescript

function logUndefined(message: string): undefined {
  console.log(message);
  return; // required: must explicitly return
}

Use void when the caller should ignore the return value entirely. Use undefined only when the return value matters and you want to be explicit that it is always undefined.

Never: A Function That Never Returns

A function with a never return type never finishes executing. It either throws an error or runs forever, so the caller never actually gets a return value.

typescript

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

An infinite loop produces the same guarantee through a different route: control never reaches the end of the function, so the return type is still never, exactly as it was for the function that throws above.

typescript

function infiniteLoop(): never {
  while (true) {
    console.log("running...");
  }
}

Because TypeScript knows a never-returning function cannot finish normally, it treats any code that would run right after the call as unreachable, and uses that fact to narrow types earlier in the function:

typescript

function fail(message: string): never {
  throw new Error(message);
}
 
function process(value: string | null) {
  if (value === null) {
    fail("value is required");
  }
  console.log(value.toUpperCase()); // value is string here
}

TypeScript understands that fail never returns, so after the if block, value must be string. This is control flow analysis combined with the never type, and it works even though fail never uses a return statement at all.

Using Never for Exhaustiveness Checking

The most practical use of never is guaranteeing that a switch statement handles every possible case. When you work with discriminated unions, never can prove that you have not missed a variant.

typescript

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

A function that computes the area checks the kind discriminant in a switch, with one case per shape and a default branch left over for anything unhandled:

typescript

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

Every branch of the switch narrows shape to one specific variant, so by the time control reaches default, nothing is left; the type of shape there is never, and the assignment compiles cleanly.

If you later add a new shape variant but forget to handle it in the switch, the default branch no longer narrows down to nothing:

text

Type '{ kind: "triangle"; base: number; height: number; }' is not assignable to type 'never'.

This is called exhaustiveness checking. It turns a missing case from a silent bug into a compiler error. For more on discriminated unions, see discriminated unions in TypeScript.

Void vs Never in Practice

The difference is easiest to see side by side. log finishes normally, so execution continues after the call:

typescript

function log(message: string): void {
  console.log(message);
}

The terminate function never finishes, so TypeScript treats any line written directly after a call to it as unreachable, the same way it treated the code after the fail function in the earlier example:

typescript

function terminate(message: string): never {
  console.error(message);
  throw new Error(message);
}

Calling terminate inside a guard clause has the same narrowing effect as the fail example earlier: TypeScript knows execution cannot continue past it, so the rest of the function treats the value as already validated.

typescript

function example(value: string | null) {
  if (value === null) {
    terminate("value was null");
  }
  console.log(value.length); // value is string here
}

For log, the caller keeps going. For terminate, the caller's code path ends. This is the fundamental difference: void finishes, never does not.

The flowchart below shows how TypeScript reasons about each type after a call:

The diagram illustrates why never is special: after a never-returning call, TypeScript treats subsequent code as dead and uses that information to narrow types in the caller.

Common Mistakes

Confusing Void With Never

typescript

// Wrong: a function that logs and returns nothing is void, not never
function log(message: string): never {
  console.log(message);
}

A function that finishes normally cannot have a never return type, so this fails to compile with an error explaining that a never-returning function cannot have a reachable end point. Use void for functions that complete without a meaningful return value.

Forgetting That Void Returns Undefined at Runtime

typescript

function log(message: string): void {
  console.log(message);
}
 
const result = log("hello");
console.log(result); // undefined (at runtime)

At compile time, result is void and TypeScript discourages using it. At runtime, it is plain undefined. The void type is a signal to humans and the compiler, not a runtime value.

Not Using Never for Exhaustiveness Checks

typescript

type Status = "loading" | "success" | "error";

A handler for this kind of status type often ends with a default branch that has no never check at all, which looks harmless until the set of possible statuses changes:

typescript

function handle(status: Status) {
  switch (status) {
    case "loading":
      return "Loading...";
    case "success":
      return "Done!";
    default:
      return "Something went wrong";
  }
}

Without that check, if someone later adds "idle" to Status, it silently falls through to the generic error message instead of failing to compile. Add a default never assertion whenever you intend to cover every case:

typescript

    default:
      const _exhaustive: never = status;
      return _exhaustive;

This way, adding a new status value becomes a compiler error instead of a silent bug. For more patterns like this, see exhaustive checks in TypeScript.