---
name: typescript-diagnosticos
description: >
  Guía canónica de códigos de error del compilador TypeScript (TS1xxx–TS7xxx).
  Extraída de diagnosticMessages.json del repositorio microsoft/TypeScript.
  Cubre los errores más frecuentes con causa, fix idiomático y anti-patrón a evitar.
  Cargar cuando se revisa código TypeScript con errores de compilación o cuando
  se necesita identificar la causa raíz de un error TSxxxx.
version: 1.0.0
herramientasPermitidas: [Read, Bash, Glob, Grep]
fuente: temp/TypeScript-main/src/compiler/diagnosticMessages.json
tags: [typescript, diagnósticos, errores, compilador, type-safety]
exclusiones:
  - "No cargar para errores de runtime JavaScript que no involucran el compilador TypeScript — si el código compila pero falla en ejecución, no hay código TS#### que diagnosticar."
  - "No cargar para errores de bundlers (Vite, webpack) que no son errores del compilador tsc — los errores de bundler tienen prefijos diferentes y causas de resolución de módulos; cargar `build-errors-typescript`."
  - "No cargar para diseñar tipos avanzados (generics, mapped types, conditional types) — para diseño del sistema de tipos cargar `typescript-avanzado`."
  - "No cargar para errores de ESLint o Prettier en archivos .ts — ESLint/Prettier no generan códigos TS####; sus códigos de error son de sus propias reglas."
evolvable: true  # default para skill estandar
---
# Diagnósticos canónicos del compilador TypeScript

Guía de referencia rápida. Fuente: `diagnosticMessages.json` del compilador TypeScript oficial.

## Cuándo NO cargar

- La pregunta es sobre errores de runtime JavaScript que no involucran al compilador — si el código compila pero falla en ejecución, no hay código TS#### que diagnosticar.
- Los errores vienen de bundlers (Vite, webpack) con prefijos distintos a TS#### — esos son errores de resolución de módulos; cargar `build-errors-typescript`.
- La tarea es diseñar tipos avanzados (generics, mapped types, conditional types) — para diseño del sistema de tipos cargar `typescript-avanzado`.
- Los errores son de ESLint o Prettier en archivos `.ts` — ESLint/Prettier no generan códigos TS####; sus reglas tienen nombres propios como `@typescript-eslint/no-explicit-any`.

---

## Errores de asignación de tipos (TS2xxx)

Los más frecuentes en proyectos con `strict: true`.

### TS2322 — Type '{0}' is not assignable to type '{1}'

**Causa:** Tipos incompatibles en asignación directa o retorno de función.

```typescript
// MAL
const x: number = "hola";          // TS2322
function getId(): number { return "abc"; }  // TS2322

// BIEN
const x: number = 42;
function getId(): number { return 123; }

// Caso literal — usar as const
const dir = "ltr" as const;        // tipo: "ltr", no string
```

**Anti-patrón a evitar:** `const x = valor as any` para silenciar el error.

---

### TS2345 — Argument of type '{0}' is not assignable to parameter of type '{1}'

**Causa:** Tipo incorrecto al llamar una función.

```typescript
function procesar(items: string[]) { ... }
procesar([1, 2, 3]);   // TS2345 — number[] no es string[]

// BIEN — corregir el tipo del argumento
procesar(["a", "b"]);
// o corregir el parámetro si el diseño lo permite
function procesar(items: Array<string | number>) { ... }
```

---

### TS2339 — Property '{0}' does not exist on type '{1}'

**Causa:** Acceso a propiedad inexistente en la interfaz/tipo.

```typescript
interface Usuario { nombre: string; }
const u: Usuario = { nombre: "Ana" };
console.log(u.email);   // TS2339

// BIEN — opción A: agregar al tipo
interface Usuario { nombre: string; email?: string; }
// BIEN — opción B: usar acceso indexado tipado
function getField<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}
```

---

### TS2353 — Object literal may only specify known properties

**Causa:** Propiedad extra en object literal (excess property check).

```typescript
interface Config { host: string; port: number; }
const cfg: Config = { host: "localhost", port: 3000, debug: true };  // TS2353

// BIEN — eliminar o agregar al tipo
// Nota: el excess property check solo aplica a object literals directos
const base = { host: "localhost", port: 3000, debug: true };
const cfg: Config = base;   // Válido — asignación indirecta no aplica la regla
```

---

### TS2540 — Cannot assign to '{0}' because it is a read-only property

**Causa:** Mutación de propiedad `readonly` o de `Readonly<T>`.

```typescript
interface Config { readonly host: string; }
const cfg: Config = { host: "localhost" };
cfg.host = "prod";   // TS2540

// BIEN — crear nuevo objeto con spread
const prodCfg: Config = { ...cfg, host: "prod" };
```

---

### TS2739 — Type '{0}' is missing the following properties from type '{1}'

**Causa:** Objeto incompleto — faltan propiedades requeridas.

```typescript
interface Producto { id: number; nombre: string; precio: number; }
const p: Producto = { id: 1, nombre: "Widget" };   // TS2739 falta precio

// BIEN
const p: Producto = { id: 1, nombre: "Widget", precio: 9.99 };
// O si la construcción es parcial
const borrador: Partial<Producto> = { id: 1, nombre: "Widget" };
```

---

### TS2741 — Property '{0}' is missing in type '{1}' but required in type '{2}'

**Causa:** Al extender o implementar una interfaz, falta implementar una propiedad requerida.

```typescript
interface Animal { nombre: string; sonido: string; }
const perro: Animal = { nombre: "Rex" };   // TS2741 falta sonido

// BIEN — completar la implementación
const perro: Animal = { nombre: "Rex", sonido: "Guau" };
// O hacer la propiedad opcional si el diseño lo permite
interface Animal { nombre: string; sonido?: string; }
```

---

## Errores de null y undefined (TS2532, TS2533, TS2571)

Activos con `strictNullChecks: true`.

### TS2532 — Object is possibly 'undefined'

**Causa:** Acceso a una propiedad sin verificar que el objeto no sea `undefined`.

```typescript
function getUser(id: number): User | undefined { ... }
const user = getUser(1);
console.log(user.nombre);   // TS2532

// BIEN — opción A: narrowing explícito
if (user !== undefined) { console.log(user.nombre); }

// BIEN — opción B: optional chaining
console.log(user?.nombre);

// BIEN — opción C: non-null assertion SOLO cuando tienes garantía externa
console.log(user!.nombre);   // Solo si sabes que no puede ser undefined
```

---

### TS2533 — Object is possibly 'null' or 'undefined'

**Causa:** Acceso sin verificar que no sea ni `null` ni `undefined`.

```typescript
const el = document.getElementById("app");
el.innerHTML = "hola";   // TS2533

// BIEN
if (el !== null) { el.innerHTML = "hola"; }
// O
el?.innerHTML;   // Silencioso si el es null — cuidado con efectos secundarios
```

---

### TS2571 — Object is of type 'unknown'

**Causa:** Intento de usar una variable de tipo `unknown` sin narrowing.

```typescript
async function fetchData(): Promise<unknown> { ... }
const data = await fetchData();
console.log(data.nombre);   // TS2571

// BIEN — type guard
function isUsuario(x: unknown): x is Usuario {
  return typeof x === "object" && x !== null && "nombre" in x;
}
if (isUsuario(data)) { console.log(data.nombre); }

// BIEN — instanceof
try { ... } catch (e: unknown) {
  if (e instanceof Error) { console.error(e.message); }
}
```

---

## Errores de módulo (TS2304, TS2305, TS2307)

### TS2304 — Cannot find name '{0}'

**Causa:** Variable, tipo o función no importado o no declarado.

```typescript
const resultado = calcular(5);   // TS2304 si calcular no está importado

// BIEN
import { calcular } from "./utils/calcular";
```

---

### TS2305 — Module '{0}' has no exported member '{1}'

**Causa:** Import de algo que no está exportado en el módulo de origen.

```typescript
import { calcular, formatear } from "./utils";   // TS2305 si formatear no se exporta

// Verificar que el módulo lo exporta
export function formatear(n: number): string { ... }
```

---

### TS2307 — Cannot find module '{0}' or its corresponding type declarations

**Causa:** Módulo sin declaraciones de tipos o ruta incorrecta.

```typescript
import express from "express";   // TS2307 si @types/express no está instalado
import { algo } from "./ruta-inexistente";   // TS2307

// BIEN — instalar tipos
// npm install --save-dev @types/express

// BIEN — declaración manual para módulos sin @types
declare module "nombre-del-modulo" {
  export function fn(): void;
}
```

---

## Errores de implicit any (TS7xxx)

Activos con `noImplicitAny: true` (incluido en `strict: true`).

### TS7006 — Parameter '{0}' implicitly has an '{1}' type

**Causa:** Parámetro de función sin anotación de tipo.

```typescript
// MAL
function duplicar(n) { return n * 2; }   // TS7006

// BIEN
function duplicar(n: number): number { return n * 2; }
```

---

### TS7010 — '{0}', which lacks return-type annotation, implicitly has an '{1}' return type

**Causa:** Función cuyo tipo de retorno no puede inferirse claramente.

```typescript
// MAL — TypeScript infiere 'any' en casos ambiguos
function cargar(url) { return fetch(url).then(r => r.json()); }

// BIEN
async function cargar(url: string): Promise<unknown> {
  const resp = await fetch(url);
  return resp.json() as unknown;
}
```

---

### TS7016 — Could not find a declaration file for module '{0}'

**Causa:** Módulo npm sin `@types/` ni declaraciones propias.

```typescript
import algo from "libreria-sin-tipos";   // TS7016

// Solución A — instalar tipos comunitarios
// npm install --save-dev @types/libreria-sin-tipos

// Solución B — declaración mínima en src/types/libreria-sin-tipos.d.ts
declare module "libreria-sin-tipos" {
  const value: unknown;
  export default value;
}

// Solución C — skipLibCheck (solo en casos excepcionales, documenta por qué)
// tsconfig.json: { "compilerOptions": { "skipLibCheck": true } }
```

---

### TS7017 — Element implicitly has an 'any' type because type '{0}' has no index signature

**Causa:** Acceso con key dinámica a un objeto sin index signature.

```typescript
const config = { host: "localhost", port: 3000 };
const key = "host";
const value = config[key];   // TS7017

// BIEN — opción A: keyof
function getConfig<K extends keyof typeof config>(key: K): typeof config[K] {
  return config[key];
}

// BIEN — opción B: Map con tipo explícito
const configMap = new Map<string, string | number>();
configMap.set("host", "localhost");

// BIEN — opción C: Record si los valores son homogéneos
const config: Record<string, string> = { host: "localhost" };
```

---

### TS7031 — Binding element '{0}' implicitly has an '{1}' type

**Causa:** Destructuring de parámetro sin anotación.

```typescript
// MAL
function render({ nombre, edad }) { ... }   // TS7031

// BIEN
interface Props { nombre: string; edad: number; }
function render({ nombre, edad }: Props) { ... }
```

---

## Errores de función y callable (TS2349, TS2355, TS2554, TS2769)

### TS2349 — This expression is not callable

**Causa:** Intentar llamar algo que no es una función según los tipos.

```typescript
const handler: string | (() => void) = "texto";
handler();   // TS2349 — podría ser string

// BIEN
if (typeof handler === "function") { handler(); }
```

---

### TS2355 — A function whose declared type is neither 'undefined', 'void', nor 'any' must return a value

**Causa:** No todos los branches de la función retornan un valor.

```typescript
function dividir(a: number, b: number): number {
  if (b !== 0) { return a / b; }
  // TS2355 — no hay return en el else
}

// BIEN
function dividir(a: number, b: number): number {
  if (b === 0) throw new Error("División por cero");
  return a / b;
}
```

---

### TS2554 — Expected {0} arguments, but got {1}

**Causa:** Número incorrecto de argumentos al llamar una función.

```typescript
function sumar(a: number, b: number): number { return a + b; }
sumar(1);          // TS2554 — faltan argumentos
sumar(1, 2, 3);    // TS2554 — argumentos de más

// BIEN — si el tercer argumento es opcional
function sumar(a: number, b: number, c?: number): number {
  return a + b + (c ?? 0);
}
```

---

### TS2769 — No overload matches this call

**Causa:** Ninguna de las sobrecargas de una función acepta los tipos de argumentos dados.

```typescript
// Función con sobrecargas
function procesar(x: string): string;
function procesar(x: number): number;
function procesar(x: string | number): string | number { return x; }

procesar(true);   // TS2769 — boolean no coincide con ninguna sobrecarga

// BIEN — verificar qué sobrecargas existen y pasar el tipo correcto
procesar("texto");   // OK
procesar(42);        // OK
```

---

## Errores de cast (TS2352, TS2693)

### TS2352 — Conversion of type '{0}' to type '{1}' may be a mistake

**Causa:** Cast (`as`) entre tipos sin superposición de propiedades.

```typescript
const n = 42;
const s = n as string;   // TS2352 — number y string no se superponen

// Anti-patrón — doble cast para evadir el error
const s = n as unknown as string;   // Compila pero es inseguro

// BIEN — convertir correctamente
const s = String(n);
```

---

### TS2693 — '{0}' only refers to a type, but is being used as a value here

**Causa:** Usar una interfaz o tipo como valor en runtime.

```typescript
interface Config { host: string; }
if (x instanceof Config) { ... }   // TS2693 — interfaces no existen en runtime

// BIEN — usar type guard con validación de propiedades
function isConfig(x: unknown): x is Config {
  return typeof x === "object" && x !== null && "host" in x;
}
```

---

## Referencia rápida — códigos por categoría

| Categoría | Códigos frecuentes |
|-----------|-------------------|
| Asignación de tipos | TS2322, TS2345, TS2739, TS2741 |
| Null/undefined | TS2532, TS2533, TS2571 |
| Propiedades | TS2339, TS2353, TS2540 |
| Módulos | TS2304, TS2305, TS2307 |
| Implicit any | TS7006, TS7010, TS7016, TS7017, TS7031 |
| Función/callable | TS2349, TS2355, TS2554, TS2769 |
| Cast | TS2352, TS2693 |

## Comandos de diagnóstico

```bash
# Ver todos los errores del proyecto agrupados por código
npx tsc --noEmit 2>&1 | grep -oP 'TS\d+' | sort | uniq -c | sort -rn

# Ver el detalle de los primeros 20 errores
npx tsc --noEmit 2>&1 | head -60

# Buscar supresiones en el código fuente
grep -rn "@ts-ignore\|@ts-expect-error\|as any\|as unknown as" \
  --include="*.ts" --include="*.tsx" \
  --exclude-dir=node_modules --exclude-dir=dist | head -30

# Verificar strict mode activo
cat tsconfig.json | grep -E '"strict"|"noImplicitAny"|"strictNullChecks"'
```

## Gotchas / Errores comunes no obvios

**TS2339 en código correcto después de actualizar TypeScript**: un upgrade de TS 4.x a 5.x puede revelar TS2339 en código que antes compilaba porque las definiciones de tipo de `@types/node` o librerías cambiaron. Causa: librerías como `express` o `mongoose` actualizan sus `@types/*` con definiciones más estrictas — una propiedad que era `any` ahora tiene tipo concreto. Fix: actualizar las dependencias `@types/*` junto con TypeScript, no solo el compilador.

**TS2590 "Expression produces a union type that is too complex to represent"**: ocurre al hacer operaciones sobre uniones grandes (más de ~25 miembros) como `Partial<A & B & C>` donde A, B, C son interfaces con muchos campos. Causa: TypeScript tiene un límite interno de complejidad en la representación de tipos. Fix: dividir la unión en tipos intermedios nombrados, o usar `interface` con `extends` en lugar de intersección `&` para reducir la profundidad de evaluación.

**`// @ts-ignore` suprime el error siguiente pero también errores reales en la misma línea**: si una línea tiene dos errores y se pone `@ts-ignore`, ambos se suprimen — incluyendo uno legítimo que debería corregirse. Fix: preferir `// @ts-expect-error` que falla en CI si el error desaparece (señal de que la supresión ya no es necesaria), y anotar el código TS#### específico en el comentario.

**TS7031 en callbacks de arrays sin anotación de contexto**: `[1, 2, 3].reduce((acc, val) => acc + val)` falla con TS7031 "Binding element 'acc' implicitly has an 'any' type" si `noImplicitAny: true` y TypeScript no puede inferir el tipo inicial del acumulador. Fix: anotar el valor inicial explícitamente: `.reduce((acc, val) => acc + val, 0)` — el tipo del acumulador se infiere del valor inicial, no del callback.

## Fuente

- `temp/TypeScript-main/src/compiler/diagnosticMessages.json` — 8,559 líneas, fuente primaria
- Compilador TypeScript oficial: `microsoft/TypeScript` (modo mantenimiento; TS 7.0 se reescribe en Go)
- Documentación oficial: https://www.typescriptlang.org/tsconfig
