NeoForge 26.1 Docs

NeoForge 26.1.2 모딩 개발 중 자주 마주치는 12가지 오류의 증상, 원인, 검증된 해결 방법을 정리합니다.

개발하다 보면 같은 오류를 반복해서 만납니다. 이 페이지는 NeoForge 26.1.2 환경에서 실제로 자주 발생하는 문제들을 모아 정리한 레퍼런스입니다. 증상을 보고 해당 항목으로 바로 이동하세요.

빠른 참조 표

#	증상	원인	해결
1	Gradle Sync 실패 (`Could not resolve neoforge`)	NeoForge 버전/Maven 저장소 미설정	`gradle.properties`의 `neo_version` + `repositories` 확인
2	`runClient` 시 크래시 (`UnsupportedClassVersionError`)	JDK 25 미만 사용	JDK 25 설치 + Gradle JVM 변경
3	인게임 보라/검정 텍스처	모델 JSON 또는 텍스처 PNG 누락	`assets/<modId>/models/item/`, `textures/item/` 확인
4	인게임 투명 블록	`parent` 모델 누락	`models/block/<name>.json`에 `"parent": "block/cube_all"` 추가
5	모드 로드 실패 (`@Mod annotation does not match modId`)	`@Mod` 값과 `mods.toml`의 `modId` 불일치	둘 다 정확히 같은 문자열로 통일
6	`/give` 명령 작동 안 함	`BlockItem` 등록 누락	`ITEMS.registerSimpleBlockItem("my_block", MY_BLOCK)` 추가
7	`Failed to create VkInstance`	GPU 드라이버 오래됨 또는 Vulkan 미지원	드라이버 업데이트 + Vulkan 1.2+ GPU 사용
8	Mermaid 다이어그램 안 보임	MDX 컴포넌트 등록 누락	`mdx-components.tsx`에 Mermaid 등록 확인
9	`runClient` 첫 실행 시 5~15분 소요	NeoForge/Minecraft assets 다운로드	정상 동작 — 첫 실행만 느림 (이후 캐시 사용)
10	Hot Reload 안 됨 (메서드 시그니처 변경 후)	JVM HotSwap 제한	`runClient` 재시작 (Debug Stop → Run)
11	Mods 메뉴에 모드 없음	JAR이 `mods/`에 없거나 손상	`build/libs/` JAR → `mods/` 복사, 재빌드
12	차원 진입 시 "Unknown dimension"	dimension JSON 누락 또는 잘못된 `modId`	`data/<modId>/dimension/<name>.json` 확인

상세 해결 가이드

1. Gradle Sync 실패

증상

Could not resolve net.neoforged:neoforge:<버전>

Gradle 탭에서 Sync를 실행하면 위 메시지와 함께 빌드가 멈춥니다.

원인

gradle.properties의 neo_version 값이 실제 존재하지 않는 버전이거나, build.gradle의 repositories 블록에 NeoForge Maven 저장소가 빠져 있는 경우입니다.

해결

gradle.properties를 열어 버전을 확인합니다.

# gradle.properties
neo_version=26.1.2.64-beta

build.gradle의 repositories 블록에 NeoForge Maven이 있는지 확인합니다.

repositories {
    maven { url = 'https://maven.neoforged.net/releases' }
}

버전이 실제로 존재하는지 NeoForge Maven에서 직접 확인하세요. 오타 하나로도 Sync가 실패합니다.

2. runClient 시 UnsupportedClassVersionError

증상

java.lang.UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime

runClient Gradle 태스크를 실행하면 JVM이 즉시 종료됩니다.

원인

NeoForge 26.1.2는 JDK 25로 컴파일됩니다. JDK 21 이하로 실행하면 클래스 버전 불일치가 발생합니다.

해결

JDK 25가 설치되어 있는지 확인합니다.

java -version
# openjdk version "25" 이상이어야 합니다

IntelliJ에서 Gradle JVM을 변경합니다.

File → Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JVM을 JDK 25로 설정합니다.

Gradle Sync를 다시 실행합니다.

3. 인게임 보라/검정 텍스처

증상

아이템이나 블록이 보라색과 검정색이 교차하는 패턴으로 표시됩니다. 이는 Minecraft가 텍스처를 찾지 못했을 때 보여주는 기본 오류 텍스처입니다.

원인

두 가지 중 하나입니다.

assets/<modId>/models/item/<name>.json 파일 누락
assets/<modId>/textures/item/<name>.png 파일 누락

해결

리소스 경로 구조를 확인합니다.

src/main/resources/
└── assets/
    └── <modId>/
        ├── models/
        │   └── item/
        │       └── <name>.json   ← 이 파일이 있어야 합니다
        └── textures/
            └── item/
                └── <name>.png    ← 이 파일이 있어야 합니다

모델 JSON의 텍스처 경로가 실제 파일 위치와 일치하는지 확인합니다.

{
  "parent": "item/generated",
  "textures": {
    "layer0": "<modId>:item/<name>"
  }
}

<modId>와 <name>이 실제 파일 경로와 정확히 일치해야 합니다. 대소문자도 구분합니다.

4. 인게임 투명 블록

증상

블록을 설치했는데 완전히 투명하게 보입니다. 블록 자체는 존재하지만 렌더링이 안 됩니다.

원인

models/block/<name>.json에 parent 필드가 없거나 잘못된 값을 가리킵니다.

해결

블록 모델 JSON을 확인합니다.

{
  "parent": "block/cube_all",
  "textures": {
    "all": "<modId>:block/<name>"
  }
}

"parent": "block/cube_all"이 없으면 Minecraft가 어떤 형태로 블록을 렌더링할지 알 수 없습니다. 커스텀 모양이 필요하다면 block/cube_all 대신 적절한 parent를 지정하세요.

5. 모드 로드 실패 (@Mod annotation mismatch)

증상

Mod class @Mod annotation does not match modId in mods.toml

게임 시작 시 모드 로딩 단계에서 크래시가 발생합니다.

원인

Java 클래스의 @Mod("...") 어노테이션 값과 META-INF/mods.toml의 modId 값이 다릅니다.

해결

두 파일을 나란히 열어 비교합니다.

// ExampleMod.java
@Mod("examplemod")  // ← 이 값과
public class ExampleMod { ... }

# mods.toml
[[mods]]
modId="examplemod"  # ← 이 값이 정확히 같아야 합니다

공백, 대소문자, 특수문자 하나라도 다르면 로드에 실패합니다. 복사-붙여넣기로 통일하는 것이 가장 안전합니다.

6. /give 명령 작동 안 함

증상

/give @s <modId>:<blockName> 명령을 입력해도 아이템이 지급되지 않거나 명령 자체가 인식되지 않습니다.

원인

블록을 등록했지만 해당 블록의 BlockItem을 아이템 레지스트리에 등록하지 않았습니다. 블록과 아이템은 별개의 레지스트리입니다.

해결

블록 등록 코드 옆에 BlockItem 등록을 추가합니다.

public static final DeferredBlock<MyBlock> MY_BLOCK =
    BLOCKS.registerBlock("my_block", MyBlock::new);
 
// BlockItem 등록이 없으면 /give가 작동하지 않습니다.
// 26.1.2: registerSimpleBlockItem 을 쓰면 아이템 id 가 설정되고
// (bare register(() -> new BlockItem(..., new Item.Properties())) 는
// "id not set" 으로 크래시) block.* 번역키도 자동 재사용된다.
public static final DeferredItem<BlockItem> MY_BLOCK_ITEM =
    ITEMS.registerSimpleBlockItem("my_block", MY_BLOCK);

7. Vulkan 드라이버 오류

증상

Failed to create VkInstance
org.lwjgl.vulkan.VK10.nvkCreateInstance

runClient 실행 직후 게임 창이 열리지 않고 크래시가 발생합니다.

원인

두 가지 중 하나입니다.

GPU 드라이버가 Vulkan 1.2 이상을 지원하지 않을 만큼 오래됨
GPU 자체가 Vulkan을 지원하지 않음 (매우 오래된 하드웨어)

해결

GPU 제조사 사이트에서 최신 드라이버를 설치합니다.

NVIDIA: nvidia.com/drivers
AMD: amd.com/support
Intel: intel.com/content/www/us/en/download-center

드라이버 업데이트 후에도 문제가 지속되면 GPU가 Vulkan 1.2를 지원하지 않는 것입니다. 이 경우 Vulkan 지원 GPU로 교체해야 합니다. NeoForge 26.1.2는 OpenGL 폴백을 제공하지 않습니다.

8. Mermaid 다이어그램 안 보임

증상

MDX 파일에 작성한 Mermaid 코드블록이 다이어그램으로 렌더링되지 않고 코드 텍스트 그대로 표시됩니다.

원인

mdx-components.tsx에 Mermaid 컴포넌트가 등록되지 않았거나, Velite 설정에서 rehypeMermaidInlineSvg 플러그인이 빠져 있습니다.

해결

velite.config.ts에 플러그인이 있는지 확인합니다.

// velite.config.ts
mdx: {
  rehypePlugins: [
    // ...
    rehypeMermaidInlineSvg,  // ← 이 줄이 있어야 합니다
  ],
}

npm run build를 실행해 Velite가 Mermaid를 SVG로 변환하는지 확인합니다. 빌드 로그에 오류가 없으면 정상입니다.

9. runClient 첫 실행 시 매우 느림

증상

runClient를 처음 실행하면 5~15분 동안 아무 반응이 없거나 다운로드 로그만 출력됩니다.

원인

정상 동작입니다. 첫 실행 시 NeoForge와 Minecraft의 assets(텍스처, 사운드, 모델 등)를 Gradle 캐시로 다운로드합니다. 파일 크기가 수 GB에 달하므로 네트워크 속도에 따라 시간이 걸립니다.

해결

기다리면 됩니다. 두 번째 실행부터는 캐시를 사용하므로 수십 초 내에 시작됩니다.

인터넷 연결이 불안정하다면 Gradle 캐시 디렉토리(~/.gradle/caches/)를 확인해 다운로드가 중단된 파일이 있는지 살펴보세요. 손상된 캐시는 해당 디렉토리를 삭제하고 재시도하면 됩니다.

10. Hot Reload 안 됨

증상

IntelliJ에서 코드를 수정하고 Build → Recompile을 실행해도 실행 중인 게임에 변경사항이 반영되지 않습니다.

원인

JVM HotSwap은 메서드 본문 변경만 지원합니다. 메서드 추가/삭제, 필드 추가/삭제, 클래스 구조 변경은 HotSwap으로 반영할 수 없습니다.

해결

구조적 변경이 있을 때는 runClient를 재시작해야 합니다.

IntelliJ 하단 Run/Debug 탭에서 Stop 버튼을 클릭합니다.
runClient Gradle 태스크를 다시 실행합니다.

메서드 본문만 수정했다면 Build → Recompile File로 HotSwap이 작동할 수 있습니다. 하지만 NeoForge 이벤트 핸들러나 레지스트리 관련 코드는 재시작이 더 안전합니다.

11. Mods 메뉴에 모드 없음

증상

게임을 실행하고 Mods 메뉴를 열었는데 내 모드가 목록에 없습니다.

원인

두 가지 중 하나입니다.

빌드한 JAR 파일이 mods/ 디렉토리에 없음
JAR 파일이 손상되었거나 mods.toml이 올바르지 않음

해결

runClient Gradle 태스크를 사용하면 JAR 복사 없이 바로 개발 환경에서 모드가 로드됩니다. 별도 JAR 배포 테스트가 목적이라면:

# 빌드
.\gradlew.bat build
 
# JAR 확인
Get-ChildItem build\libs\
 
# 실제 Minecraft mods/ 디렉토리에 복사
Copy-Item build\libs\<modId>-<version>.jar "C:\Users\<사용자>\AppData\Roaming\.minecraft\mods\"

JAR 내부에 META-INF/mods.toml이 있는지 확인합니다.

# JAR 내용 확인 (ZIP으로 열기)
Expand-Archive build\libs\<modId>-<version>.jar -DestinationPath temp-jar-check
Get-ChildItem temp-jar-check\META-INF\

mods.toml이 없으면 NeoForge가 모드로 인식하지 않습니다.

12. 차원 진입 시 "Unknown dimension"

증상

커스텀 차원 포탈을 통과하거나 /execute in <modId>:<dimensionName> 명령을 실행하면 다음 오류가 발생합니다.

Unknown dimension: <modId>:<dimensionName>

원인

두 가지 중 하나입니다.

data/<modId>/dimension/<name>.json 파일이 없음
JSON 파일의 modId가 실제 모드 ID와 다름

해결

데이터팩 경로 구조를 확인합니다.

src/main/resources/
└── data/
    └── <modId>/
        └── dimension/
            └── <name>.json   ← 이 파일이 있어야 합니다

dimension.json의 최소 구조를 확인합니다.

{
  "type": "<modId>:dimension_type_name",
  "generator": {
    "type": "minecraft:noise",
    "settings": "minecraft:overworld"
  }
}

type 필드의 <modId>가 mods.toml의 modId와 정확히 일치해야 합니다.

문제가 해결되지 않을 때

위 목록에 없는 오류라면 다음 순서로 접근하세요.

크래시 로그 확인: logs/latest.log 또는 crash-reports/ 디렉토리
NeoForge 포럼 검색: forums.neoforged.net
NeoForge Discord: #modder-support 채널에 로그와 함께 질문

질문할 때는 반드시 다음을 포함하세요.

NeoForge 버전 (26.1.2.64-beta)
JDK 버전 (java -version 출력)
크래시 로그 전문 (요약 금지)
재현 방법

빠른 참조 표

#	증상	원인	해결
1	Gradle Sync 실패 (`Could not resolve neoforge`)	NeoForge 버전/Maven 저장소 미설정	`gradle.properties`의 `neo_version` + `repositories` 확인
2	`runClient` 시 크래시 (`UnsupportedClassVersionError`)	JDK 25 미만 사용	JDK 25 설치 + Gradle JVM 변경
3	인게임 보라/검정 텍스처	모델 JSON 또는 텍스처 PNG 누락	`assets/<modId>/models/item/`, `textures/item/` 확인
4	인게임 투명 블록	`parent` 모델 누락	`models/block/<name>.json`에 `"parent": "block/cube_all"` 추가
5	모드 로드 실패 (`@Mod annotation does not match modId`)	`@Mod` 값과 `mods.toml`의 `modId` 불일치	둘 다 정확히 같은 문자열로 통일
6	`/give` 명령 작동 안 함	`BlockItem` 등록 누락	`ITEMS.registerSimpleBlockItem("my_block", MY_BLOCK)` 추가
7	`Failed to create VkInstance`	GPU 드라이버 오래됨 또는 Vulkan 미지원	드라이버 업데이트 + Vulkan 1.2+ GPU 사용
8	Mermaid 다이어그램 안 보임	MDX 컴포넌트 등록 누락	`mdx-components.tsx`에 Mermaid 등록 확인
9	`runClient` 첫 실행 시 5~15분 소요	NeoForge/Minecraft assets 다운로드	정상 동작 — 첫 실행만 느림 (이후 캐시 사용)
10	Hot Reload 안 됨 (메서드 시그니처 변경 후)	JVM HotSwap 제한	`runClient` 재시작 (Debug Stop → Run)
11	Mods 메뉴에 모드 없음	JAR이 `mods/`에 없거나 손상	`build/libs/` JAR → `mods/` 복사, 재빌드
12	차원 진입 시 "Unknown dimension"	dimension JSON 누락 또는 잘못된 `modId`	`data/<modId>/dimension/<name>.json` 확인

상세 해결 가이드

1. Gradle Sync 실패

증상

Could not resolve net.neoforged:neoforge:<버전>

Gradle 탭에서 Sync를 실행하면 위 메시지와 함께 빌드가 멈춥니다.

원인

gradle.properties의 neo_version 값이 실제 존재하지 않는 버전이거나, build.gradle의 repositories 블록에 NeoForge Maven 저장소가 빠져 있는 경우입니다.

해결

gradle.properties를 열어 버전을 확인합니다.

# gradle.properties
neo_version=26.1.2.64-beta

build.gradle의 repositories 블록에 NeoForge Maven이 있는지 확인합니다.

repositories {
    maven { url = 'https://maven.neoforged.net/releases' }
}

버전이 실제로 존재하는지 NeoForge Maven에서 직접 확인하세요. 오타 하나로도 Sync가 실패합니다.

2. runClient 시 UnsupportedClassVersionError

증상

java.lang.UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime

runClient Gradle 태스크를 실행하면 JVM이 즉시 종료됩니다.

원인

NeoForge 26.1.2는 JDK 25로 컴파일됩니다. JDK 21 이하로 실행하면 클래스 버전 불일치가 발생합니다.

해결

JDK 25가 설치되어 있는지 확인합니다.

java -version
# openjdk version "25" 이상이어야 합니다

IntelliJ에서 Gradle JVM을 변경합니다.

File → Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle JVM을 JDK 25로 설정합니다.

Gradle Sync를 다시 실행합니다.

3. 인게임 보라/검정 텍스처

증상

아이템이나 블록이 보라색과 검정색이 교차하는 패턴으로 표시됩니다. 이는 Minecraft가 텍스처를 찾지 못했을 때 보여주는 기본 오류 텍스처입니다.

원인

두 가지 중 하나입니다.

assets/<modId>/models/item/<name>.json 파일 누락
assets/<modId>/textures/item/<name>.png 파일 누락

해결

리소스 경로 구조를 확인합니다.

src/main/resources/
└── assets/
    └── <modId>/
        ├── models/
        │   └── item/
        │       └── <name>.json   ← 이 파일이 있어야 합니다
        └── textures/
            └── item/
                └── <name>.png    ← 이 파일이 있어야 합니다

모델 JSON의 텍스처 경로가 실제 파일 위치와 일치하는지 확인합니다.

{
  "parent": "item/generated",
  "textures": {
    "layer0": "<modId>:item/<name>"
  }
}

<modId>와 <name>이 실제 파일 경로와 정확히 일치해야 합니다. 대소문자도 구분합니다.

4. 인게임 투명 블록

증상

블록을 설치했는데 완전히 투명하게 보입니다. 블록 자체는 존재하지만 렌더링이 안 됩니다.

원인

models/block/<name>.json에 parent 필드가 없거나 잘못된 값을 가리킵니다.

해결

블록 모델 JSON을 확인합니다.

{
  "parent": "block/cube_all",
  "textures": {
    "all": "<modId>:block/<name>"
  }
}

5. 모드 로드 실패 (@Mod annotation mismatch)

증상

Mod class @Mod annotation does not match modId in mods.toml

게임 시작 시 모드 로딩 단계에서 크래시가 발생합니다.

원인

Java 클래스의 @Mod("...") 어노테이션 값과 META-INF/mods.toml의 modId 값이 다릅니다.

해결

두 파일을 나란히 열어 비교합니다.

// ExampleMod.java
@Mod("examplemod")  // ← 이 값과
public class ExampleMod { ... }

# mods.toml
[[mods]]
modId="examplemod"  # ← 이 값이 정확히 같아야 합니다

공백, 대소문자, 특수문자 하나라도 다르면 로드에 실패합니다. 복사-붙여넣기로 통일하는 것이 가장 안전합니다.

6. /give 명령 작동 안 함

증상

/give @s <modId>:<blockName> 명령을 입력해도 아이템이 지급되지 않거나 명령 자체가 인식되지 않습니다.

원인

블록을 등록했지만 해당 블록의 BlockItem을 아이템 레지스트리에 등록하지 않았습니다. 블록과 아이템은 별개의 레지스트리입니다.

해결

블록 등록 코드 옆에 BlockItem 등록을 추가합니다.

public static final DeferredBlock<MyBlock> MY_BLOCK =
    BLOCKS.registerBlock("my_block", MyBlock::new);
 
// BlockItem 등록이 없으면 /give가 작동하지 않습니다.
// 26.1.2: registerSimpleBlockItem 을 쓰면 아이템 id 가 설정되고
// (bare register(() -> new BlockItem(..., new Item.Properties())) 는
// "id not set" 으로 크래시) block.* 번역키도 자동 재사용된다.
public static final DeferredItem<BlockItem> MY_BLOCK_ITEM =
    ITEMS.registerSimpleBlockItem("my_block", MY_BLOCK);

7. Vulkan 드라이버 오류

증상

Failed to create VkInstance
org.lwjgl.vulkan.VK10.nvkCreateInstance

runClient 실행 직후 게임 창이 열리지 않고 크래시가 발생합니다.

원인

두 가지 중 하나입니다.

GPU 드라이버가 Vulkan 1.2 이상을 지원하지 않을 만큼 오래됨
GPU 자체가 Vulkan을 지원하지 않음 (매우 오래된 하드웨어)

해결

GPU 제조사 사이트에서 최신 드라이버를 설치합니다.

NVIDIA: nvidia.com/drivers
AMD: amd.com/support
Intel: intel.com/content/www/us/en/download-center

8. Mermaid 다이어그램 안 보임

증상

MDX 파일에 작성한 Mermaid 코드블록이 다이어그램으로 렌더링되지 않고 코드 텍스트 그대로 표시됩니다.

원인

mdx-components.tsx에 Mermaid 컴포넌트가 등록되지 않았거나, Velite 설정에서 rehypeMermaidInlineSvg 플러그인이 빠져 있습니다.

해결

velite.config.ts에 플러그인이 있는지 확인합니다.

// velite.config.ts
mdx: {
  rehypePlugins: [
    // ...
    rehypeMermaidInlineSvg,  // ← 이 줄이 있어야 합니다
  ],
}

npm run build를 실행해 Velite가 Mermaid를 SVG로 변환하는지 확인합니다. 빌드 로그에 오류가 없으면 정상입니다.

9. runClient 첫 실행 시 매우 느림

증상

runClient를 처음 실행하면 5~15분 동안 아무 반응이 없거나 다운로드 로그만 출력됩니다.

원인

해결

기다리면 됩니다. 두 번째 실행부터는 캐시를 사용하므로 수십 초 내에 시작됩니다.

10. Hot Reload 안 됨

증상

IntelliJ에서 코드를 수정하고 Build → Recompile을 실행해도 실행 중인 게임에 변경사항이 반영되지 않습니다.

원인

JVM HotSwap은 메서드 본문 변경만 지원합니다. 메서드 추가/삭제, 필드 추가/삭제, 클래스 구조 변경은 HotSwap으로 반영할 수 없습니다.

해결

구조적 변경이 있을 때는 runClient를 재시작해야 합니다.

IntelliJ 하단 Run/Debug 탭에서 Stop 버튼을 클릭합니다.
runClient Gradle 태스크를 다시 실행합니다.

11. Mods 메뉴에 모드 없음

증상

게임을 실행하고 Mods 메뉴를 열었는데 내 모드가 목록에 없습니다.

원인

두 가지 중 하나입니다.

빌드한 JAR 파일이 mods/ 디렉토리에 없음
JAR 파일이 손상되었거나 mods.toml이 올바르지 않음

해결

runClient Gradle 태스크를 사용하면 JAR 복사 없이 바로 개발 환경에서 모드가 로드됩니다. 별도 JAR 배포 테스트가 목적이라면:

# 빌드
.\gradlew.bat build
 
# JAR 확인
Get-ChildItem build\libs\
 
# 실제 Minecraft mods/ 디렉토리에 복사
Copy-Item build\libs\<modId>-<version>.jar "C:\Users\<사용자>\AppData\Roaming\.minecraft\mods\"

JAR 내부에 META-INF/mods.toml이 있는지 확인합니다.

# JAR 내용 확인 (ZIP으로 열기)
Expand-Archive build\libs\<modId>-<version>.jar -DestinationPath temp-jar-check
Get-ChildItem temp-jar-check\META-INF\

mods.toml이 없으면 NeoForge가 모드로 인식하지 않습니다.

12. 차원 진입 시 "Unknown dimension"

증상

커스텀 차원 포탈을 통과하거나 /execute in <modId>:<dimensionName> 명령을 실행하면 다음 오류가 발생합니다.

Unknown dimension: <modId>:<dimensionName>

원인

두 가지 중 하나입니다.

data/<modId>/dimension/<name>.json 파일이 없음
JSON 파일의 modId가 실제 모드 ID와 다름

해결

데이터팩 경로 구조를 확인합니다.

src/main/resources/
└── data/
    └── <modId>/
        └── dimension/
            └── <name>.json   ← 이 파일이 있어야 합니다

dimension.json의 최소 구조를 확인합니다.

{
  "type": "<modId>:dimension_type_name",
  "generator": {
    "type": "minecraft:noise",
    "settings": "minecraft:overworld"
  }
}

type 필드의 <modId>가 mods.toml의 modId와 정확히 일치해야 합니다.

문제가 해결되지 않을 때

위 목록에 없는 오류라면 다음 순서로 접근하세요.

크래시 로그 확인: logs/latest.log 또는 crash-reports/ 디렉토리
NeoForge 포럼 검색: forums.neoforged.net
NeoForge Discord: #modder-support 채널에 로그와 함께 질문

질문할 때는 반드시 다음을 포함하세요.

NeoForge 버전 (26.1.2.64-beta)
JDK 버전 (java -version 출력)
크래시 로그 전문 (요약 금지)
재현 방법

자주 발생하는 문제와 해결법

빠른 참조 표

상세 해결 가이드

1. Gradle Sync 실패

2. runClient 시 UnsupportedClassVersionError

3. 인게임 보라/검정 텍스처

4. 인게임 투명 블록

5. 모드 로드 실패 (@Mod annotation mismatch)

6. /give 명령 작동 안 함

7. Vulkan 드라이버 오류

8. Mermaid 다이어그램 안 보임

9. runClient 첫 실행 시 매우 느림

10. Hot Reload 안 됨

11. Mods 메뉴에 모드 없음

12. 차원 진입 시 "Unknown dimension"

문제가 해결되지 않을 때

On this page

자주 발생하는 문제와 해결법

빠른 참조 표

상세 해결 가이드

1. Gradle Sync 실패

2. runClient 시 UnsupportedClassVersionError

3. 인게임 보라/검정 텍스처

4. 인게임 투명 블록

5. 모드 로드 실패 (@Mod annotation mismatch)

6. /give 명령 작동 안 함

7. Vulkan 드라이버 오류

8. Mermaid 다이어그램 안 보임

9. runClient 첫 실행 시 매우 느림

10. Hot Reload 안 됨

11. Mods 메뉴에 모드 없음

12. 차원 진입 시 "Unknown dimension"

문제가 해결되지 않을 때

On this page