[Machine Learning] CUDA error: device-side assert triggered — 원인과 해결법 정리

RuntimeError: CUDA error: device-side assert triggered

또는

RuntimeError: CUDA error: device-side assert triggered
Exception raised from <function> at ... in file ...

이 에러는 PyTorch를 사용할 때, 특히 GPU 환경에서 모델을 학습시키는 중에 갑자기 터지는 경우가 많다.
처음 이 에러를 만나면 코드 어디에서 문제가 발생한 건지 알기 어렵고, 에러 메시지도 명확하지 않기 때문에 당황하게 된다.

---

1. 원인 요약

이 에러는 GPU 내부에서 실행되던 코드가 잘못된 입력이나 상태를 만나 'assert'에 걸렸을 때 발생한다.
예를 들어, 어떤 값이 특정 범위를 벗어났거나, 예상하지 못한 데이터 타입이 들어왔을 때 발생할 수 있다.
GPU 연산은 기본적으로 비동기적(asynchronous) 으로 실행되기 때문에, 에러 메시지가 실제 원인과 다른 줄에서 발생하는 것처럼 보일 수 있다.

즉, 에러가 나는 이유는 단순하지만, 찾는 데 시간이 오래 걸릴 수 있다는 것이 이 에러의 핵심이다.

---

2. 대표적인 원인 3가지

2.1 클래스 인덱스 범위 초과

이 경우가 가장 흔하다.
nn.CrossEntropyLoss()는 분류 문제에서 자주 사용하는 손실 함수인데, 이 함수는 정답(label) 값이 0 이상 (num_classes - 1 이하) 의 정수여야 한다.

예를 들어, 클래스가 10개이면 라벨 값은 0~9 사이여야 한다. 그런데 라벨 값이 -1이거나 10 이상일 경우, GPU 내부에서 "이건 말이 안 돼" 하고 assert 에러를 터뜨린다.

이유는 내부적으로 라벨을 index로 사용하기 때문이다.
배열의 11번째 값을 가져오라는데 배열은 10개뿐이면 당연히 터진다.

해결 방법:

assert labels.max().item() < num_classes
assert labels.min().item() >= 0

데이터셋을 로딩한 직후, 라벨에 대해 위처럼 검사를 해두면 원인을 미리 파악할 수 있다.

---

2.2 잘못된 데이터 타입

CrossEntropyLoss는 target이 반드시 LongTensor여야 한다.
만약 float 형식(FloatTensor, DoubleTensor)이면 내부적으로는 인덱스로 해석할 수 없어서 문제가 된다.

해결 방법:

labels = labels.long()

데이터셋을 만들 때 라벨이 float으로 되어 있다면, 학습 전에 .long()을 꼭 붙여주자.

---

2.3 ignore_index 설정 누락

ignore_index는 라벨 중 학습에 사용하지 않을 값을 지정할 때 사용한다. 예를 들어, 마스킹된 토큰의 라벨을 -100으로 넣는 경우가 이에 해당한다.

이 값을 무시하라고 ignore_index=-100 설정을 하지 않으면, -100이라는 라벨을 클래스 인덱스로 인식하려다 문제가 발생한다.

해결 방법:

loss_fn = nn.CrossEntropyLoss(ignore_index=-100)

실제 NLP 작업에서는 매우 흔하게 쓰이므로 이 설정이 빠지지 않도록 주의해야 한다.

---

3. 디버깅 팁: 정확한 에러 위치 찾기

이 에러가 특히 골치 아픈 이유는, GPU 연산이 비동기적이라는 점 때문이다.
즉, 에러는 모델의 마지막 출력 줄에서 나지만, 실제 원인은 라벨 전처리에 있을 수 있다.

3.1 CUDA_LAUNCH_BLOCKING=1 설정

이 환경변수를 설정하면 GPU 연산을 동기식(synchronous) 으로 바꿔준다.
즉, 에러가 발생한 정확한 코드 줄에서 바로 오류가 출력되기 때문에 디버깅이 훨씬 쉬워진다.

사용 예:

CUDA_LAUNCH_BLOCKING=1 python train.py

3.2 CPU에서 실행

GPU 환경에서 문제가 계속 발생한다면, 모델과 데이터를 CPU로 옮겨서 실행해 보자.
CPU에서는 에러가 즉시 발생하고 정확한 위치를 알려주기 때문에 원인을 빠르게 찾을 수 있다.

예시 코드:

model.cpu()
inputs = inputs.cpu()
labels = labels.cpu()