Fix: “DataLoader worker is killed by signal: Bus error” (공유 메모리 `/dev/shm`) — AI Toolkit의 LTX-2 LoRA

LTX-2 LoRA 트레이닝이 Bus error로 크래시한다면, 거의 대부분은 공유 메모리(/dev/shm) 압박 때문입니다. PyTorch DataLoader worker + prefetching이 큰 비디오 배치(프레임이 많은 샘플)를 메모리에 여러 개 잡아두면서 문제가 발생합니다.

빠른 해결 체크리스트(여기부터)

✅ Fix A 적용: dataset config에서 num_workers와 prefetch_factor를 낮추기
✅ Docker로 self-host 중이면 Fix B 적용: --shm-size로 /dev/shm 늘리기
✅ 트레이닝을 다시 실행하고 로그에서 “out of shared memory” / “Bus error”가 더 이상 나오지 않는지 확인
✅ 121 frames로 학습 중이면 GPU OOM도 함께 대비(아래 Notes 참고)

1) 같은 이슈가 맞는지 확인

로그에 아래와 비슷한 내용이 있으면, 이 문서가 다루는 문제일 가능성이 높습니다:

DataLoader worker (pid XXX) is killed by signal: Bus error

It is possible that dataloader's workers are out of shared memory

Please try to raise your shared memory limit

자주 보이는 키워드:

Bus error
out of shared memory
DataLoader worker, shared memory limit, /dev/shm 언급

2) 무슨 일이 벌어지고 있나

LTX-2 트레이닝은 비디오 배치(샘플당 많은 프레임)를 사용합니다.
DataLoader worker 수가 많고 prefetching까지 켜져 있으면, AI Toolkit이 여러 개의 큰 배치를 /dev/shm에 큐잉할 수 있습니다.
/dev/shm이 부족하면 worker 프로세스가 크래시 → Bus error → 트레이닝 중단으로 이어집니다.

RunComfy는 기본적으로 공유 메모리를 늘려서 제공하지만, dataset/설정(특히 num_frames가 121처럼 큰 경우)에 따라서는 여전히 한계를 넘을 수 있습니다.

3) 해결 방법

Tip: 한 번에 한 가지만 바꾸세요. 대부분은 Fix A로 해결됩니다.

Fix A(권장): DataLoader worker + prefetch 줄이기

트레이닝 데이터는 그대로 두고, 공유 메모리 압박만 줄이는 방법입니다.

어디서 바꾸나(RunComfy UI):

Your Training Job Panel 열기
오른쪽 위 Show Advanced 클릭
YAML config에서 datasets: 아래의 dataset item( folder_path가 들어있는 블록) 찾기
해당 dataset item 안에 아래 키를 추가/조정

먼저 이걸 시도(대부분 충분):

num_workers: 1

prefetch_factor: 1

그래도 크래시하면(가장 안정적이지만 느림):

num_workers: 0

prefetch_factor: null

⚠️ 중요:

num_workers: 0이면 prefetch_factor: null을 꼭 설정하세요(정확히 null).
worker/prefetch를 낮추는 건 속도(throughput)에 영향을 주지 품질에는 영향이 없습니다. 데이터 로딩 방식만 바뀝니다.

Fix B(self-host / Docker): `/dev/shm` 늘리기

Docker로 AI Toolkit을 직접 운영 중이라면, 컨테이너의 shared memory를 늘리세요:

docker run --shm-size=32g ...

or safer:

docker run --shm-size=64g ...

안정성을 위해 Fix A도 함께 적용할 수 있습니다.

Fix C(여전히 한계에 걸리면): 샘플당 메모리 줄이기

dataset이 너무 무거운 경우, 아래 중 하나 이상을 낮추세요:

num_frames
resolution
batch_size

4) 해결 확인

해결되면 보통 이렇게 보입니다:

DataLoader 단계에서 멈추지 않고 트레이닝 step이 계속 진행됨
크래시 로그에 “out of shared memory” / “Bus error”가 반복되지 않음

self-host 환경이라면 컨테이너 내부에서 /dev/shm 크기가 실제로 커졌는지도 확인하세요.

Notes(자주 따라오는 문제: GPU OOM)

121 frames는 매우 무겁습니다. /dev/shm를 해결한 뒤에도 GPU OOM이 날 수 있습니다.

권장: 121-frame 트레이닝은 H200
그 외: batch_size / resolution / num_frames를 낮추세요

복사/붙여넣기 예시(dataset 블록)

datasets:

folder_path: /app/ai-toolkit/datasets/your_dataset
num_frames: 121

resolution: [512, 768]

caption_ext: "txt"

# Fix shared memory Bus error (start here):

num_workers: 1

prefetch_factor: 1

# If still crashing, use this instead (slowest but most stable):

# num_workers: 0

# prefetch_factor: null

FAQ

이게 데이터셋이 깨졌다는 뜻인가요?

대부분 아닙니다. 이건 나쁜 데이터셋 문제가 아니라 DataLoader의 shared memory 제한 문제입니다.

`num_workers: 0`일 때 왜 `prefetch_factor: null`이 필요한가요?

worker가 없으면 prefetching은 사용되지 않습니다. null로 두면 config에서 유효하지 않거나 사용되지 않는 prefetch 동작을 피할 수 있습니다.

Fix B(`/dev/shm` 늘리기)만 하면 되나요?

RunComfy라면 Fix A부터 하세요. Docker self-host라면 Fix B가 필요한 경우가 많고, Fix A도 안정성에 도움이 됩니다.

Bus error는 해결됐는데 GPU OOM이 납니다. 다음은?

batch_size, resolution, num_frames를 낮추거나 더 큰 GPU를 사용하세요(121 frames는 H200 권장).

Fix: “DataLoader worker is killed by signal: Bus error” (공유 메모리 /dev/shm) — AI Toolkit의 LTX-2 LoRA