TypeScript: 'Type null is not assignable to type...' 엄격한 Null 체크 에러와 3가지 예외 처리법

TypeScript null 할당 에러 및 옵셔널 체이닝 해결 가이드
3초 요약: 이렇게 고치세요
  • 원인: strictNullChecks가 켜져 있으면, null을 허용하지 않은 타입 변수에 null이 섞일 수 있는 값을 대입하려 할 때 컴파일러가 막음
  • 해결: 속성 접근은 옵셔널 체이닝(?.) / 기본값이 필요하면 널 병합(??) / 100% 값이 있다고 확신하면 Non-Null 단언(!)
  • 주의: ! 단언은 컴파일러 경고를 강제로 끄는 것이라, 실제로 값이 없으면 그대로 런타임 에러로 이어짐 — 남용 금지
const displayName: string = user?.name ?? "비회원";
↓ 왜 이런 에러가 나는지 원리 보기

비동기로 데이터를 받아오거나 DOM 요소를 다룰 때 TypeScript가 'Type null is not assignable to type...' 에러를 띄우는 경우가 있습니다. strictNullChecks 옵션이 왜 이런 경고를 내는지와, 실무에서 자주 쓰는 예외 처리 방법 세 가지를 정리합니다.

왜 'Type null is not assignable' 에러가 발생하는가

이 에러가 표시되는 주범은 타입스크립트의 핵심 옵션인 strictNullChecks가 활성화되어 있기 때문입니다. 기존 자바스크립트는 값이 비어있는 null이나 undefined 상태의 객체 속성에 접근할 때 런타임 오류(TypeError: Cannot read properties of null)를 일으키며 프로그램이 중단됩니다. 타입스크립트는 이를 컴파일 시점에 미리 잡아내기 위해, 명시적으로 null을 허용(Union Type)하지 않은 일반 타입 변수에는 null 값을 아예 대입할 수 없도록 강제 차단합니다. API 응답이 아직 안 왔거나 실패했을 때의 초기값을 null로 잡아두는 패턴에서 이 에러를 가장 많이 만나게 됩니다. 

let userName: string = null;
// 에러: Type 'null' is not assignable to type 'string'.

기존 자바스크립트에서는 값이 null인 상태로 user.name처럼 속성에 접근하면 그 즉시 런타임 크래시로 이어집니다. 타입스크립트 컴파일러는 타입에 null이 섞여 있으면 코드 단계에서 미리 경고해 예외 처리(가드)를 강제로 유도함으로써 이런 런타임 크래시를 사전에 막아줍니다.

'Type null is not assignable' 에러 해결책 3가지

방법 A: 옵셔널 체이닝(Optional Chaining - ?. ) 사용하기

객체의 값이 null 또는 undefined일 수 있는 상황에서 속성을 안전하게 탐색하게 해 주는 가장 범용적인 해결 방법입니다. 객체가 비어있다면 속성 접근을 멈추고 즉시 undefined를 반환합니다. 

interface User {
  name: string;
}

// user 데이터가 서버로부터 로드되기 전에는 null 상태일 수 있음
let user: User | null = null;

// 에러: Object is possibly 'null'.
console.log(user.name);

// 해결: ?. 연산자를 사용하여 안전하게 참조
console.log(user?.name); // user가 null이면 에러 없이 undefined 출력

방법 B: 널 병합 연산자(Nullish Coalescing - ?? )로 기본값 지정하기

데이터가 null이어서 반환값이 비어있을 때, 이를 대체할 안전한 기본 값(Fallback)을 설정하는 방법입니다. 

let user: { name: string } | null = null;

// 에러: Type 'string | undefined' is not assignable to type 'string'.
const displayName: string = user?.name;

// 해결: ?? 연산자로 null/undefined일 때 적용할 기본 문자열 지정
const displayNameSafe: string = user?.name ?? "비회원";
console.log(displayNameSafe); // "비회원" 출력

방법 C: Non-Null 단언 연산자(Non-null Assertion Operator - ! ) 활용

타입스크립트 컴파일러는 객체가 비어있을 수 있다고 경고하지만, 개발자가 논리적으로 "이 값은 무조건 데이터가 들어있다"고 보장할 수 있을 때 사용하는 방식입니다. 컴파일러의 간섭을 강제로 끕니다. (예외가 발생할 경우 크래시 위험이 있으므로 주의해서 사용해야 합니다.) 

// React에서 useRef로 DOM 요소를 지정할 때 주로 활용됩니다.
const inputRef = useRef<HTMLInputElement | null>(null);

const handleFocus = () => {
  // inputRef.current가 마운트 시점에 존재함을 개발자가 보장 (!)
  inputRef.current!.focus();
};

자바스크립트 프로젝트를 타입스크립트로 전환하던 중, useRef를 쓰는 곳마다 !를 습관적으로 붙이다가 조건부로 렌더링되는 모달 내부의 ref에도 똑같이 붙여서 실제로 null인 상태에서 .focus()를 호출해 런타임 에러를 낸 적이 있습니다. 컴파일러가 막아주던 걸 !로 직접 풀어버렸으니 당연한 결과였는데, 그 뒤로는 마운트가 확실히 보장되는 ref에만 !를 쓰고 나머지는 ?.로 바꿨습니다.

요약: Null 예외 처리 제어 매트릭스

컴파일 에러를 해결하기 위한 예외 제어 요약 테이블입니다.

상황 잠재적 위협 대응할 기법
단순 객체 속성 참조 런타임 프로퍼티 탐색 시 크래시 유발 위험 옵셔널 체이닝 (?.)
비어있는 상태 대체용 UI 노출 빈 값(undefined)이 사용자 화면에 지저분하게 노출됨 널 병합 연산자 (??)
DOM 맵핑 등 100% 할당 확신 불필요한 컴파일러의 반복적인 에러 경고 띄움 Non-Null 단언 (!)
공식 참고 레퍼런스

strictNullChecks 옵션과 Nullable 타입 처리는 공식 문서에서 더 자세히 확인할 수 있습니다.

호마다의 웹개발 팁

세 가지 방법 중 어떤 걸 쓸지는 '값이 없을 가능성을 어떻게 다룰지'에 달려 있습니다. non-null 단언(!)은 편하지만 실제로 값이 없을 때는 그대로 런타임 에러로 이어지므로 남용하지 않는 게 좋습니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

TypeScript: Unknown vs Any 타입 차이점과 안전한 타입 가드(Type Guard)

이미지
3초 요약: 이렇게 고치세요 원인: any 는 타입 검사 자체를 포기하는 선언이라, 잘못된 속성 접근이 컴파일 시점엔 통과했다가 런타임에 터짐 해결: 외부 API 응답처럼 타입을 확신할 수 없는 데이터는 unknown 으로 받고, data is T 형태의 타입 가드로 검증한 뒤에만 사용 주의: 타입 가드 내부에서 as Record<string, unknown> 같은 임시 캐스팅으로 속성을 하나씩 검사하는 절차를 생략하면 unknown 을 쓰는 의미가 없어짐 function isUserProfile(data: unknown): data is UserProfile { ... } ↓ 왜 any가 위험한지 원리 보기 실무에서 대규모 TypeScript 프로젝트를 마이그레이션하거나, 외부 API 또는 레거시 라이브러리를 통합하다 보면 필연적으로 "타입을 확신할 수 없는 데이터"를 다루게 됩니다. 이때 많은 개발자들이 급한 마음에 가장 손쉬운 탈출구인 any 를 사용하곤 합니다. 하지만 이는 TypeScript의 가장 큰 무기인 타입 안정성을 스스로 내려놓는 행위이자, 미래의 나에게 런타임 에러라는 시한폭탄을 던지는 것과 같습니다. any 가 왜 위험한지, TypeScript 3.0에서 도입된 unknown 이 이를 어떻게 막아주는지, 그리고 실무에서 바로 써먹을 수 있는 사용자 정의 타입 가드(User-Defined Type Guards) 작성 패턴을 정리합니다. any의 위험성과 unknown의 등장 프로덕션 환경에서 발생한 실제 에러 로그를 분석해 보면, 꽤 많은 비율이 TypeError: Cannot read properties of undefined 에서 시작합니다. 그리고 그 이면에는 높은 확률로 any 타입이 자리 잡고 있죠. any: 타입...
자세한 내용 보기

Next.js 하이드레이션 오류 원인과 해결법 완벽 정리

이미지
3초 요약: 이렇게 고치세요 원인: 서버가 렌더링한 초기 HTML과 브라우저가 처음 그린 HTML 구조가 서로 달라서 발생 — React는 둘이 같을 거라 믿고 결합을 시도하다가 실패함 해결: 잘못된 태그 중첩이면 마크업 수정 / window · localStorage 참조면 useEffect 로 이동 / 시간·랜덤값처럼 매번 달라지는 값이면 ssr: false 로 분리 주의: suppressHydrationWarning 은 경고를 숨길 뿐 원인을 고치는 게 아니라서, 불가피한 텍스트 불일치(타임스탬프 등)에만 제한적으로 써야 함 const [isMounted, setIsMounted] = useState(false); useEffect(() => setIsMounted(true), []); if (!isMounted) return null; // 서버와 첫 클라이언트 렌더는 항상 동일하게 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js를 쓰다 보면 콘솔에 "Hydration failed because the initial UI does not match..."라는 붉은 에러가 뜰 때가 있습니다. 빌드는 멀쩡히 끝났는데 화면이 그려진 직후에 갑자기 나는 에러라서 처음 보면 당황스럽습니다. 원인은 대부분 서버와 클라이언트가 그린 첫 화면이 미묘하게 다르기 때문이고, 패턴이 정해져 있어서 하나씩 짚어보면 금방 잡힙니다. 하이드레이션(Hydration), 정확히 어떤 과정인가 Next.js의 핵심 기능은 서버 사이드 렌더링(SSR)입니다. 서버는 먼저 사용자에게 정적인 HTML 뼈대를 빠르게 그려서 브라우저에 내려보내 줍니다. 그 후, 브라우저(클라이언트)가 이 정적인 HTML 위에 React의 자바스크립트 코드와 이벤트 리스너를 결합하여 ...
자세한 내용 보기

Next.js App Router에서 getServerSideProps 대체 및 데이터 페칭법

이미지
3초 요약: 이렇게 고치세요 원인: App Router는 서버 컴포넌트에서 직접 async/await를 쓸 수 있어 getServerSideProps / getStaticProps 가 아예 없어짐 해결: 빌드 시 캐싱(SSG) → 기본 fetch / 매 요청 최신화(SSR) → { cache: 'no-store' } / 주기 갱신(ISR) → { next: { revalidate: N } } 주의: getServerSideProps 안에 있던 인증 체크 로직은 이제 컴포넌트 함수 내부나 미들웨어로 옮겨야 함 const res = await fetch(url, { cache: 'no-store' }); // SSR과 동일하게 매번 재요청 ↓ 왜 이런 에러가 나는지 원리 보기 Next.js 13 이상에서 App Router가 표준이 되면서, Pages Router에서 쓰던 getServerSideProps 와 getStaticProps 가 더 이상 동작하지 않습니다. 두 함수가 사라진 설계적 이유와, 이를 대체하는 데이터 패칭 방식을 정리했습니다. 왜 getServerSideProps와 getStaticProps가 사라졌을까 과거 Next.js는 페이지 컴포넌트 내부에서만 특정 정적 함수( getServerSideProps 등)를 실행하여 데이터를 미리 받아온 뒤, 이를 컴포넌트의 props 로 넘겨주는 복잡한 직렬화 구조를 가졌습니다. 이로 인해 컴포넌트 간 깊이가 깊어지면 'Props Drilling(프로퍼티 대물림)'이 심해져 코드 관리가 몹시 까다로웠습니다. App Router 환경에서는 서버 컴포넌트(Server Component)가 표준이 됨에 따라 컴포넌트 내에서 직접 비동기 함수(async/await)를 작성할 수 있게 되었습...
자세한 내용 보기