TypeScript 오류 메시지 읽기와 흔한 오류

오류 메시지의 구조

TypeScript 오류는 두 부분으로 되어 있다.

상세 부분은 「왜?」에 대한 답의 사슬이다. 한 줄 내려갈 때마다 더 구체적인 원인이 나오고, 맨 아래 줄이 고칠 곳이다.

type SomethingComplex = { foo: number; bar: string };
declare function take(arg: SomethingComplex): void;
declare function getBar(): string;
 
const fail = { foo: 123, bar: getBar };
take(fail);

error TS2345: Argument of type '{ foo: number; bar: () => string; }'
              is not assignable to parameter of type 'SomethingComplex'.
  Types of property 'bar' are incompatible.               ← 왜? bar가 안 맞는다
    Type '() => string' is not assignable to type 'string'. ← 왜? 함수를 넣었다

맨 아래 줄을 보면 getBar를 호출하지 않고 함수 자체를 넣었다(getBar()를 써야 한다). 편집기 툴팁은 보통 상세 사슬을 먼저, 요약을 나중에 보여 준다.

읽는 순서: 맨 아래 줄 → 그 위 줄로 올라가며 어느 속성·인자에서 어긋났는지 확인 → 맨 위 줄로 어느 호출·대입인지 확인한다. 타입이 길어 ...로 잘리면 noErrorTruncation을 켠다.

자주 만나는 오류 코드

설치 문제에서 오는 오류도 있다. @types/react가 node_modules 안에 두 벌 들어오면 「Interface 'X' cannot simultaneously extend types 'Component' and 'Component'」처럼 같은 이름의 타입이 서로 다르다는 오류가 난다. 잠금 파일을 지우고 다시 설치하거나, 패키지 관리자의 dedupe·overrides로 한 벌만 남긴다. 라이브러리는 @types/react를 peerDependencies로 둬야 이런 일이 없다.

흔한 함정

리터럴 넓히기

const s = 'foo'의 타입은 'foo'지만, 객체 속성과 let은 넓은 타입(string)으로 추론된다. 나중에 바뀔 수 있기 때문이다.

declare function iTakeFoo(foo: 'foo'): void;
 
const test = { someProp: 'foo' };          // { someProp: string }
// iTakeFoo(test.someProp);                // TS2345: string은 'foo'가 아니다
 
const ok1 = { someProp: 'foo' } as const;  // readonly { someProp: 'foo' }
const ok2 = { someProp: 'foo' } satisfies { someProp: 'foo' };
iTakeFoo(ok1.someProp);
iTakeFoo(ok2.someProp);

해결은 as const, satisfies, 선언 타입 표기 중 하나다. 'foo' as 'foo'처럼 값마다 단언하는 것은 옛 방식이다.

빈 객체로 시작해 속성 붙이기

JavaScript에서 흔한 let foo = {}; foo.bar = 1은 TS2339가 된다. foo의 타입이 {}로 정해졌기 때문이다.

그 밖에

• 함수를 호출하지 않고 넘김: 위 bar: getBar 예처럼 () => T와 T가 어긋난다는 메시지가 나오면 괄호를 빠뜨린 것이다.
• 콜백 매개변수의 any: const f = (a, b) => …처럼 타입을 받을 곳이 없으면 TS7006. 변수에 함수 타입을 적으면 매개변수가 추론된다.
• any가 퍼진다: 타입 없는 JS 함수의 반환값이 any면 그 값을 쓴 식도 모두 any가 되어 오류가 사라진다. 오류가 「없어서」 이상할 때는 마우스를 올려 any인지 본다.

오류를 덮는 방법

고치는 것이 먼저다. 당장 고칠 수 없을 때는 가장 좁은 범위로, 이유를 남기고 덮는다.

진단용 플래그

정리

• 오류는 맨 아래 줄부터 읽는다. 위로 올라가며 어느 속성·인자인지 확인한다.
• 같은 오류는 TS 코드로 검색한다. 코드는 대입(2322·2345), 없는 속성(2339·2353·2741), 이름·모듈(2304·2307), strict 계열(7006·18048·2564)로 묶어 기억한다.
• 리터럴은 as const·satisfies로 지키고, 객체는 한 번에 만든다.
• 덮을 때는 @ts-expect-error에 사유를 남긴다.

TypeScript 오류 메시지는 「무엇이 틀렸나」에서 시작해 「정확히 어디가 틀렸나」로 내려가는 설명이다.

관련 노트: TypeScript: 개념과 문법 한눈에 보기, TypeScript 타입 호환성, TypeScript 프로젝트 설정, TypeScript 컴파일러 내부 구조