TypeScript Compiler-Fehler verstehen und lösen

TypeScript-Fehlermeldungen sind präzise, aber manchmal kryptisch. Wer lernt, sie zu lesen und die häufigsten Muster zu erkennen, debuggt deutlich schneller. Dieser Ratgeber geht die wichtigsten Fehlerkategorien durch und zeigt konkrete Lösungswege.

Type X is not assignable to type Y

Der häufigste Fehler. TypeScript erwartet einen bestimmten Typ, bekommt aber einen anderen.

function zeigeAlter(alter: number) {
  console.log(`Alter: ${alter}`);
}

// Fehler: Argument of type 'string' is not assignable to parameter of type 'number'.
zeigeAlter("25");

// Korrekt
zeigeAlter(25);
zeigeAlter(parseInt("25", 10));

Häufige Ursache: Du passt den Typen der Variablen nicht an den Typen der Funktion an. Lösung: Entweder konvertierst du den Wert, oder du erweiterst den Funktionsparameter um den zweiten Typen.

Object is possibly null / undefined

Dieser Fehler tritt auf, wenn strictNullChecks aktiv ist und du auf ein Objekt zugreifst, das null oder undefined sein könnte.

function findeElement(id: string): HTMLElement | null {
  return document.getElementById(id);
}

const element = findeElement("hauptinhalt");

// Fehler: Object is possibly 'null'.
element.textContent = "Hallo";

// Lösung 1: Explizite Prüfung
if (element !== null) {
  element.textContent = "Hallo";
}

// Lösung 2: Optional Chaining
element?.setAttribute("aria-hidden", "true");

// Lösung 3: Non-Null Assertion (nur wenn sicher)
element!.textContent = "Hallo";

Property X does not exist on type Y

TypeScript findet das angesprochene Property nicht in der Typdefinition.

interface Produkt {
  id: number;
  name: string;
}

const produkt: Produkt = { id: 1, name: "Laptop" };

// Fehler: Property 'preis' does not exist on type 'Produkt'.
console.log(produkt.preis);

Ursachen und Lösungen:

// Ursache 1: Property fehlt im Interface
interface ProduktMitPreis {
  id: number;
  name: string;
  preis: number;
}

// Ursache 2: Tippfehler im Property-Namen
console.log(produkt.name); // statt 'naem'

// Ursache 3: Falsches Interface verwendet
// Prüfe, ob du wirklich das richtige Interface importiert hast

Type X has no properties in common with type Y

Dieser Fehler erscheint häufig bei Object Literals, wenn TypeScript sieht, dass du Felder übergibst, die im Typen nicht existieren.

interface Konfiguration {
  host: string;
  port: number;
}

// Fehler: Object literal may only specify known properties,
// and 'debug' does not exist in type 'Konfiguration'.
const config: Konfiguration = {
  host: "localhost",
  port: 3000,
  debug: true,
};

// Lösung 1: Feld aus dem Literal entfernen
const config2: Konfiguration = {
  host: "localhost",
  port: 3000,
};

// Lösung 2: Feld zum Interface hinzufügen
interface KonfigurationMitDebug {
  host: string;
  port: number;
  debug?: boolean;
}

Argument of type X is not assignable to parameter of type never

Dieser Fehler taucht oft in switch-Statements auf, wenn TypeScript einen Fall als nicht erreichbar betrachtet.

type Aktion = "starten" | "stoppen";

function verarbeiteAktion(aktion: Aktion) {
  switch (aktion) {
    case "starten":
      console.log("Gestartet");
      break;
    case "stoppen":
      console.log("Gestoppt");
      break;
    default:
      // Hier: aktion hat Typ 'never'
      // TypeScript weiß, dass alle Fälle abgedeckt sind
      const unerreichbar: never = aktion;
      throw new Error(`Unbekannte Aktion: ${unerreichbar}`);
  }
}

Das ist tatsächlich ein nützliches Muster: Wenn du dem Union Type einen neuen Wert hinzufügst, aber vergisst, den switch zu erweitern, meldet TypeScript einen Fehler beim never-Check.

Cannot find module X or its corresponding type declarations

TypeScript findet die Typdefinitionen für ein Modul nicht.

// Fehler: Could not find a declaration file for module 'lodash'.
import _ from "lodash";

Lösung: Installiere die Typdefinitionen aus @types.

// Im Terminal ausführen:
// npm install --save-dev @types/lodash

// Dann funktioniert der Import
import _ from "lodash";

Für Bibliotheken ohne @types-Paket kannst du eine minimale Deklarationsdatei erstellen:

// types/lodash.d.ts
declare module "lodash";

Type X is not assignable to type Y: Types of property Z are incompatible

Dieser Fehler tritt bei verschachtelten Typen auf, wenn ein einzelnes Feld nicht passt.

interface Tierhalter {
  name: string;
  tier: {
    art: "hund" | "katze";
    name: string;
  };
}

const halter: Tierhalter = {
  name: "Maria",
  tier: {
    art: "hamster", // Fehler: "hamster" ist nicht in "hund" | "katze"
    name: "Flauschig",
  },
};

TypeScript zeigt genau, welches Feld in welchem Unter-Objekt nicht stimmt.

Im Playground Fehler reproduzieren

Das Playground ist der schnellste Weg, einen Fehler zu isolieren. Kopiere den problematischen Code, füge ihn ein, und TypeScript zeigt dir sofort alle Fehler mit genauen Positionen. Oft reicht es schon, den minimalen Code zu schreiben, der den Fehler reproduziert, um die Ursache zu verstehen.

Fazit

TypeScript-Fehlermeldungen sind präzise und hilfreich, wenn du weißt, wie du sie liest. Der Typ in der Fehlermeldung zeigt immer, was TypeScript erwartet und was es bekommen hat. Diese beiden Informationen zusammen führen in den meisten Fällen direkt zur Lösung.