마인크래프트 모드 충돌 해결 가이드 — 크래시 리포트 읽고 원인 좁히기

시작하기 전에 — 어떤 종류의 문제인지 먼저 분류

'모드팩이 안 된다'는 한 마디 안에 사실 네 가지 다른 문제가 섞여 있습니다. 첫 5분은 무슨 종류의 문제인지 분류하는 데 쓰세요. 종류에 따라 해결법이 완전히 달라지기 때문에, 분류 없이 무작정 손대면 엉뚱한 데서 시간을 씁니다.

A. 게임 자체가 안 켜짐 (런처에서 'Launching...' → 잠깐 후 닫힘) → 보통 Java 버전 또는 메모리 문제

B. Mojang 로고까지 떴다가 크래시 → 모드 로딩 중 충돌. crash-report 생성됨

C. 메인 메뉴까지는 떴는데 월드 진입 시 크래시 → 월드 데이터·차원·청크 관련 모드 충돌

D. 플레이 중 갑자기 크래시 또는 게임 멈춤 → 특정 모드 동작 시 트리거되는 충돌

A와 B의 차이가 가장 헷갈리는데, 인스턴스 폴더의 crash-reports/ 폴더에 새 파일이 생성되었는지로 구분할 수 있습니다. 파일이 있으면 B/C/D, 없으면 A입니다.

1단계 — crash-report 위치와 기본 읽기

모드팩이 크래시 리포트를 남겼다면 인스턴스 폴더 → crash-reports/ 안에 crash-<날짜>_<시각>-client.txt(또는 -server.txt) 형식의 파일이 생깁니다. 가장 최근 시간의 파일을 메모장이나 VS Code로 엽니다.

파일 구조 — 어디를 봐야 하나

크래시 리포트는 길어 보이지만, 처음 볼 곳은 정해져 있습니다. 아래는 실제 로그가 아니라 구조를 설명하기 위한 형식 예시입니다.

---- Minecraft Crash Report ----
// (농담 한 줄 — 무시해도 됩니다)
Time: <시각>
Description: <어느 단계에서 죽었는지>
<예외 클래스>: <메시지>          ← 에러 종류
	at <패키지>.<클래스>.<메서드>(<파일>:<줄>)   ← 스택 트레이스
	at ...

읽는 순서는 이렇습니다.

Description — 어느 단계에서 죽었는지 (월드 렌더링 중인지, 틱 처리 중인지 등)

예외 클래스와 메시지 — java.lang.OutOfMemoryError 같은 에러 종류. 아래 2단계에서 종류별로 정리합니다

스택 트레이스의 at 줄 — net.minecraft으로 시작하지 않는 패키지 이름이 보이면 그게 모드 쪽 코드입니다. 그 패키지 이름을 검색하면 어느 모드인지 찾을 수 있습니다

⚠️ 패키지 이름만 보고 모드를 짐작하지 마세요. 리포트 아래쪽에는 로드된 모드 목록(Forge/NeoForge는 'Mod List', Fabric은 'Fabric Mods')이 함께 들어 있습니다. 여기서 모드 ID를 대조해 확정하는 게 정확합니다. 모드 로딩 단계에서 죽은 경우에는 리포트나 로그가 문제 모드 파일 이름을 직접 알려 주기도 합니다.

2단계 — 자주 보이는 에러 종류와 의미

에러 종류만 보고도 어디서 시작할지 감이 옵니다.

java.lang.OutOfMemoryError: Java heap space

할당된 힙 메모리가 부족합니다. 모드팩 인스턴스 설정에서 -Xmx 값을 올려 주세요. 다만 PC 전체 RAM을 넘겨 할당하면 더 나빠지니, 할당량 잡는 법은 [메모리·JVM 인수 가이드](/guides/memory-jvm-args-guide/)를 보세요.

java.lang.UnsupportedClassVersionError

Java 버전 불일치입니다. 모드팩이 요구하는 것보다 낮은 버전의 Java로 실행할 때 나옵니다. 마인크래프트 1.20.5 이상(1.21 포함)은 Java 21이 필요하고, 1.18~1.20.4는 Java 17입니다. Prism Launcher처럼 인스턴스별로 Java를 지정하는 런처라면 인스턴스 설정에서 직접 맞춰야 합니다.

java.lang.NoSuchMethodError 또는 NoClassDefFoundError

모드·라이브러리 버전 불일치입니다. 자주 나오는 경우:

의존 라이브러리 모드(API·Lib류)의 버전이 요구 버전과 다름

같은 마인크래프트 버전이라도 다른 로더용 빌드를 넣음 (Forge용 모드를 NeoForge 인스턴스에 넣는 등)

모드팩 일부만 업데이트해 모드끼리 버전이 어긋남

java.lang.NullPointerException

가장 정보가 적은 에러입니다. 스택 트레이스의 at 줄에서 모드 패키지를 찾는 게 유일한 단서입니다. 해당 모드가 특정되면:

그 모드의 config 파일을 백업 후 삭제 → 기본값으로 재생성해 보기

그래도 나면 3단계 이분 검색으로 상대 모드를 찾기

월드 로딩 중 '누락된 레지스트리 항목' 계열 오류

진행 중인 월드에서 모드를 제거했거나, 다른 모드팩의 월드를 그대로 가져왔을 때 나옵니다. 월드에 저장된 블록·아이템 ID를 현재 모드 목록이 더 이상 제공하지 못하는 상태입니다. 빼기 전 모드를 되돌려 넣거나, 백업한 월드로 복원하는 게 정답입니다.

Mixin apply failed

Mixin으로 바닐라 코드를 수정하는 모드끼리 같은 지점을 건드려 충돌한 경우입니다. 성능·렌더링 모드가 Mixin을 많이 쓰기 때문에 이 계열에서 자주 보입니다. 메시지에 어느 Mixin이 어느 대상 클래스에서 실패했는지 나오므로, 그 모드의 GitHub Issues에서 같은 에러를 검색하는 게 가장 빠릅니다.

Description이 Watching Server인 리포트

서버 워치독이 만든 리포트입니다. 한 틱이 비정상적으로 오래 걸려 서버가 멈춘 것으로 판단하고 강제 종료한 것으로, 크래시라기보다 과부하 신호입니다. 자동화 라인 폭주나 과도한 청크 로딩이 흔한 원인입니다. 성능 쪽 대응은 [성능 최적화 가이드](/guides/performance-optimization/)를 보세요.

3단계 — 이분 검색법으로 충돌 모드 찾기

crash-report에서 모드 이름이 명확히 안 나오는 경우, 가장 확실한 방법은 이분 검색(binary search)입니다.

방법

mods 폴더 백업 (전체 복사)

모드 폴더 안의 모드 절반을 다른 폴더로 임시 이동 (예: 200개 중 100개)

게임 켜보기:

- 크래시 안 나면 → 옮긴 100개에 범인 있음 → 그 100개를 다시 절반으로 나눠서 반복 - 크래시 나면 → 남긴 100개에 범인 있음 → 그 100개를 절반으로 나눠서 반복

200 → 100 → 50 → 25 → 12 → 6 → 3 → 1: 여덟 번 정도면 1개로 좁혀집니다

무작정 모드를 하나씩 끄는 것보다 훨씬 빠릅니다.

주의사항

의존성 모드(Library)를 임시 이동하면 그 모드를 의존하는 다른 모드들이 모두 로드 실패합니다. 'API', 'Library', 'Lib', 'Core'가 이름에 들어간 모드는 옮기지 말고 남겨 두세요.

로더가 띄우는 '의존성 누락' 화면은 충돌이 아니라 이분 검색의 부작용입니다. 그 모드를 되돌려 넣고 다른 절반을 시도하세요.

모드팩이 제공하는 모드 목록에서 의존 관계를 미리 확인해 두면 헛돌지 않습니다.

4단계 — 구조적으로 같이 쓸 수 없는 조합

다음은 '충돌이 잦다'가 아니라 원래 함께 설치할 수 없는 조합입니다.

Forge/NeoForge 모드 + Fabric 모드 — 로더가 다르므로 섞을 수 없습니다. 같은 이름의 모드라도 로더별 빌드를 따로 받아야 합니다.

OptiFine + Oculus — [Oculus](/mods/oculus/) 저장소가 "OptiFine과 호환되지 않으며 앞으로도 그럴 일은 없다"고 명시합니다. 셰이더는 둘 중 하나로만 굴리세요.

Embeddium + Rubidium — 둘 다 Sodium 계열 렌더러라 동시에 설치할 수 없습니다. 하나만 고르세요.

마인크래프트 버전이 다른 모드 — 1.20.1용 모드를 1.21.1 인스턴스에 넣으면 로드되지 않거나 크래시합니다.

미니맵처럼 기능이 겹치는 모드(예: 미니맵 모드 두 개)는 대개 크래시를 내지는 않지만, 화면과 단축키가 중복될 뿐 얻는 게 없습니다. 하나로 정리하는 편이 낫습니다.

5단계 — config 충돌 해결

에러 메시지에 Failed to load config 또는 특정 config 파일 경로가 등장하면, 해당 config 파일에 문제가 있는 경우입니다.

해결 순서

인스턴스의 config/ 폴더에서 해당 모드의 파일(또는 폴더)을 찾습니다. 모드에 따라 config/-common.toml 같은 단일 파일일 수도, config// 폴더일 수도 있습니다

문제의 config를 다른 곳으로 옮겨 백업

원본 삭제

게임 재실행 → 모드가 기본값으로 config를 새로 생성

게임이 정상 실행되면 백업본과 새 파일을 비교해 어떤 항목이 문제였는지 확인

6단계 — 마지막 수단

위 단계로도 해결 안 되면:

1. 백업한 세이브로 복원

진행 중이던 월드가 영향받은 경우, 백업해둔 세이브로 돌아가는 게 가장 안전합니다. 백업이 없다면 saves/<월드이름>/ 폴더 전체를 다른 곳에 복사한 뒤 모드 변경을 시도하세요. 복구 절차는 [세이브 손상 복구 가이드](/guides/world-save-recovery/)에 정리돼 있습니다.

2. 모드팩 디스코드 / CurseForge Issues

같은 모드팩을 플레이하는 다른 사용자도 비슷한 문제를 겪었을 가능성이 큽니다. 모드팩 페이지의 'Issues' 탭이나 공식 디스코드에서 에러 메시지의 핵심 부분을 검색해보세요.

3. 모드 제작자에게 보고

모드 단독 사용에서도 같은 문제가 재현되면 해당 모드의 GitHub Issues 페이지에 신고합니다. 이때 다음을 함께 첨부하면 처리가 빠릅니다:

crash-report 전체 (Pastebin이나 Gist에 업로드)

사용 중인 마인크래프트 버전·로더·Java 버전

모드 목록

재현 방법

미리 막는 습관 — 충돌 발생 빈도 줄이기

트러블슈팅 자체가 시간을 많이 잡아먹기 때문에, 처음부터 충돌 가능성을 줄이는 게 중요합니다.

인스턴스 복제로 백업 — 모드 추가 전 항상 인스턴스 통째로 복제. 충돌 시 즉시 복원

한 번에 한 모드씩 추가 — 5개를 한 번에 추가하면 충돌 시 어느 게 원인인지 모름

모드 페이지의 Comments·Issues 미리 확인 — 알려진 충돌은 대개 여기에 적혀 있음

모드팩 업데이트 전에 백업 — 업데이트로 모드 구성이 바뀌면 기존 월드와 어긋날 수 있음

Optional 모드와 Required 모드 구분 — Required로 표시된 모드는 빼지 말 것

마무리

100~200개 모드가 동시에 굴러가는 환경에서 크래시는 드문 일이 아닙니다. 중요한 건 크래시가 났을 때 어디부터 볼지 아는 것입니다. 리포트에서 에러 종류를 확인하고, 모드가 특정되지 않으면 이분 검색으로 좁히고, 백업만 잘 해두면 최악의 경우에도 진행 중인 월드를 잃지 않습니다.

함께 읽으면 좋은 글

[성능 최적화 가이드](/guides/performance-optimization/) — 렉·TPS·렌더 설정

[메모리·JVM 인수 가이드](/guides/memory-jvm-args-guide/) — RAM 할당과 GC 튜닝

[모드팩 설치 실패 해결 가이드](/guides/modpack-installation-troubleshooting/) — 게임이 켜지기 전 단계 문제

[세이브 손상 복구 가이드](/guides/world-save-recovery/) — 사고 이후 복구