Debugging TypeScript

TypeScript does not just add types to JavaScript — it gives you a second set of eyes that never sleeps. The compiler catches entire categories of bugs before you run a single line of code. But that only works if you know how to read what it is telling you, and how to use the type system as an active debugging tool rather than a hurdle to work around.

Debugging in TypeScript happens at two levels. At compile time, the type checker flags inconsistencies you might not notice until a user hits them in production. At runtime, you still need the usual toolkit of logging and inspection, but TypeScript shapes how you approach those problems too. This lesson covers both layers: how to decode error messages, how to use types to find logic bugs, and how to apply runtime techniques without losing type safety.

Reading TypeScript Error Messages

TypeScript errors are famously verbose, but they follow a pattern. The outermost message tells you what went wrong. The indented lines underneath trace the path the compiler took to reach that conclusion. Reading them bottom-up is usually faster than top-down.

type User = {
  id: number;
  name: string;
  role: "admin" | "editor" | "viewer";
};

function promote(user: User): User {
  return { ...user, role: "superadmin" };
}

This produces: Type '"superadmin"' is not assignable to type '"admin" | "editor" | "viewer"'. The error tells you exactly which value is wrong and exactly what values are allowed. The fix is either to add "superadmin" to the union or to remove it from the return value. There is no ambiguity.

When the error comes from a deeply nested generic, the message grows longer, but the structure stays the same. Find the innermost line — that is where the actual mismatch is.

Using the Type System to Find Logic Bugs

The most powerful debugging technique in TypeScript is not a tool — it is a mental model. When something behaves unexpectedly, add explicit types to the values involved. If the compiler agrees with your annotation, you have confirmed what the code actually does. If it disagrees, you have found the bug.

type CartItem = {
  productId: string;
  quantity: number;
  unitPrice: number;
};

function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => {
    // Bug: forgot to multiply by quantity
    return sum + item.unitPrice;
  }, 0);
}

const cart: CartItem[] = [
  { productId: "abc", quantity: 3, unitPrice: 9.99 },
  { productId: "xyz", quantity: 1, unitPrice: 4.99 },
];

// Type is correct (number), but the logic is wrong.
// TypeScript cannot catch arithmetic mistakes, but narrowing the
// intermediate type helps you reason about each step.
const itemTotal = (item: CartItem): number => item.unitPrice * item.quantity;

function calculateTotalFixed(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + itemTotal(item), 0);
}

console.log(calculateTotal(cart));       // 14.98 — wrong
console.log(calculateTotalFixed(cart));  // 34.96 — correct

TypeScript cannot catch logical errors like forgetting to multiply, but extracting the computation into a typed helper forces you to name the concept — and named concepts are easier to verify.

Exhaustiveness Checks with never

The never type is TypeScript's way of representing something that should never happen. You can exploit this to write code that breaks at compile time if you forget to handle a new variant of a union.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rectangle"; width: number; height: number }
  | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "rectangle":
      return shape.width * shape.height;
    case "triangle":
      return (shape.base * shape.height) / 2;
    default: {
      // If a new Shape variant is added and this switch is not updated,
      // TypeScript will error here: shape is no longer never.
      const exhaustiveCheck: never = shape;
      throw new Error(`Unhandled shape: ${JSON.stringify(exhaustiveCheck)}`);
    }
  }
}

const c: Shape = { kind: "circle", radius: 5 };
console.log(area(c).toFixed(2)); // 78.54

This pattern means you can safely add variants to a union knowing the compiler will point you to every switch statement that needs updating. It turns a runtime crash into a compile-time error.

Type Guards and Narrowing for Runtime Inspection

When you receive data from an external source — an API response, a file, user input — TypeScript cannot verify its shape at compile time. Type guards let you perform that check at runtime while preserving type information inside the guarded block.

type ApiSuccess = { status: "ok"; data: string[] };
type ApiError = { status: "error"; message: string };
type ApiResponse = ApiSuccess | ApiError;

function isSuccess(response: ApiResponse): response is ApiSuccess {
  return response.status === "ok";
}

function handleResponse(response: ApiResponse): void {
  if (isSuccess(response)) {
    // TypeScript knows response is ApiSuccess here
    console.log("Items:", response.data.join(", "));
  } else {
    // TypeScript knows response is ApiError here
    console.error("Failed:", response.message);
  }
}

handleResponse({ status: "ok", data: ["apple", "banana"] });
handleResponse({ status: "error", message: "Not found" });

User-defined type guards (response is ApiSuccess) are especially useful when debugging data flow. They make the validation logic explicit, self-documenting, and testable in isolation.

Debugging Utilities Without Losing Type Safety

console.log works fine for most runtime debugging, but TypeScript offers patterns that go further. A typed debug helper preserves the value's type while logging it, which means you can insert it inline without breaking the surrounding code.

function debug<T>(label: string, value: T): T {
  console.log(`[debug] ${label}:`, value);
  return value;
}

type Order = { id: string; total: number; isPaid: boolean };

function processOrder(order: Order): string {
  const validated = debug("raw order", order);
  const withTax = debug("with tax", { ...validated, total: validated.total * 1.2 });
  return debug("result", `Order ${withTax.id}: $${withTax.total.toFixed(2)}`);
}

processOrder({ id: "ORD-001", total: 49.99, isPaid: false });

Because debug is generic and returns T, TypeScript still knows the exact type at every step. You can insert it anywhere in a pipeline without adding type assertions or breaking downstream inference.

Try It Yourself

A parseConfig function receives raw user input and should return a validated config object. Add a type guard, an exhaustiveness check, and the debug utility to trace the data through the function.

type LogLevel = "info" | "warn" | "error";

type Config = {
  host: string;
  port: number;
  logLevel: LogLevel;
};

const LOG_LEVELS: LogLevel[] = ["info", "warn", "error"];

function isLogLevel(value: unknown): value is LogLevel {
  return typeof value === "string" && (LOG_LEVELS as string[]).includes(value);
}

function debug<T>(label: string, value: T): T {
  console.log(`[debug] ${label}:`, value);
  return value;
}

function parseConfig(raw: Record<string, unknown>): Config {
  const host = debug("host", typeof raw.host === "string" ? raw.host : "localhost");
  const port = debug("port", typeof raw.port === "number" ? raw.port : 3000);
  const logLevel = debug(
    "logLevel",
    isLogLevel(raw.logLevel) ? raw.logLevel : "info"
  );

  return { host, port, logLevel };
}

function describeLogLevel(level: LogLevel): string {
  switch (level) {
    case "info":
      return "Informational messages only";
    case "warn":
      return "Warnings and errors";
    case "error":
      return "Errors only";
    default: {
      const _exhaustive: never = level;
      throw new Error(`Unknown level: ${_exhaustive}`);
    }
  }
}

const config = parseConfig({ host: "example.com", port: 8080, logLevel: "warn" });
console.log(describeLogLevel(config.logLevel));

const fallback = parseConfig({ logLevel: "verbose" });
console.log(describeLogLevel(fallback.logLevel));

Try changing "verbose" to "error" and observe how the fallback path changes. Then add a new LogLevel variant and watch the exhaustiveness check fail to compile until you handle it.

Key Takeaways

TypeScript errors read bottom-up: the innermost line is where the actual type mismatch is
Adding explicit intermediate types is itself a debugging technique — mismatches surface the bug
The never type enables exhaustiveness checks that turn forgotten union cases into compile errors
User-defined type guards (value is T) validate runtime data while preserving type narrowing inside the guarded block
A generic debug<T> helper logs values inline without breaking type inference or requiring extra variables

Pro Tip: When a TypeScript error message is hard to parse, simplify the code until the error disappears, then add complexity back one piece at a time. The moment the error reappears is the moment you have isolated the cause. This binary-search approach works faster than reading the full stack of generic instantiation traces the compiler sometimes emits.