가이드
Minecraft 플러그인 오류 고치는 법
2026년 10월 18일 업데이트
플러그인이 로드되지 않으면 서버는 거의 항상 이유를 알려 줘요. 시작할 때 콘솔에서 플러그인 이름 몇 줄 위나 아래에 이유가 나와요. 로그의 그 부분을 읽는 법만 익히면 대부분의 오류는 1분이면 고칠 수 있어요. 흔한 오류와 그 의미를 정리했어요.
서버 버전과 플러그인이 할 일을 적으세요.
Codexe로 이걸 생성하기단계별 안내
1.시작 로그 열기
콘솔이나 서버 폴더의
logs/latest.log를 읽으세요. 호스팅 패널이라면 패널의 콘솔이나 파일 관리자를 쓰세요.2.플러그인 이름 검색하기
플러그인 이름이 나오는 첫 번째 오류를 찾으세요.
[ERROR]나[WARN]으로 시작하는 줄과 그 아래의 스택 트레이스가 중요한 부분이에요.3.첫 줄과 "Caused by" 줄 읽기
첫 줄은 무엇이 실패했는지, 마지막
Caused by:줄은 보통 왜 실패했는지 알려 줘요. 플러그인 자체 패키지 이름이 들어간 줄은 코드의 어디에서 실패했는지 보여 줘요.4.아래 목록과 맞춰 보기
대부분의 시작 오류는 버전, Java, 의존성 문제이고, 메시지에 어느 쪽인지 나와요.
5.하나만 고치고 재시작하기
하나만 바꾸고, 재시작하고(
/reload가 아니라), 로그를 다시 읽으세요. 한 플러그인의 오류가 다른 플러그인의 오류를 일으킬 수 있어요.
흔한 오류
| 보이는 메시지 | 의미 | 해결 방법 |
|---|---|---|
Unsupported API version 1.21 | 플러그인의 api-version이 서버보다 새 버전이에요. | 내 서버용 버전을 받거나 서버를 업데이트하세요. |
Invalid plugin.yml 또는 Jar does not contain plugin.yml과 함께 나오는 Could not load 'plugins/X.jar' | 플러그인 디스크립터가 없거나 YAML 오류가 있거나, 파일이 플러그인이 아니에요. | 소스, 모드, zip이 아니라 플러그인을 내려받았는지 확인하세요. 직접 빌드했다면 plugin.yml을 고치세요. |
UnsupportedClassVersionError, "class file version 65.0" | 플러그인이 서버에서 쓰는 것보다 새 Java를 필요로 해요(61 = Java 17, 65 = Java 21, 69 = Java 25). | 서버를 그 Java로 실행하거나, 플러그인을 내 Java용으로 다시 빌드하세요. |
NoClassDefFoundError 또는 ClassNotFoundException | 플러그인에 필요한 클래스가 없어요. 의존성 플러그인이 빠졌거나, 라이브러리가 .jar에 셰이딩되지 않았거나, 이 버전에 그 API가 없어요. | 오류에 나온 플러그인(Vault, ProtocolLib)을 설치하거나, 내 버전용 빌드를 쓰세요. |
Unknown/missing dependency plugins | depend에 적힌 플러그인이 설치되어 있지 않아요. | plugins/에 설치하세요. |
Error occurred while enabling X (Is it up to date?) | 플러그인이 로드됐지만 onEnable에서 크래시가 났어요. | Caused by 줄을 읽으세요. 설정 오류나 빠진 의존성인 경우가 많아요. |
Ambiguous plugin name | 같은 플러그인의 .jar 파일 두 개가 plugins/에 있어요. | 예전 것을 삭제하세요. |
로드와 관계없는 오류
- 플러그인은 초록색인데 명령어에 "Unknown command"가 나와요: 명령어가
plugin.yml에 없거나, 다른 플러그인이 같은 이름을 쓰고 있어요. - "I'm sorry, but you do not have permission": 플레이어에게 권한 노드가 없어요. 플러그인 페이지에서 노드를 확인하고 권한 플러그인으로 부여하세요.
- config.yml을 수정한 뒤 오류: YAML에는 탭이 아니라 스페이스를 써야 하고,
:나&로 시작하는 텍스트는 따옴표로 감싸야 해요. - 재시작하면 작동하는데 /reload 후에 망가져요: 플러그인이
/reload를 지원하지 않아요. 대신 재시작하세요.
서버에 필요한 Java
Minecraft 1.20.5 이상은 Java 21, 26.x는 Java 25, 1.18~1.20.4는 Java 17이 필요해요. 서버가 쓰는 것과 같은 Java로 java -version을 실행하세요(호스팅 패널에서는 보통 Docker 이미지나 Java 버전이라는 설정이에요). 예전 Java용으로 빌드된 플러그인은 새 Java에서 실행되지만, 반대는 안 돼요.
Codexe로 만든 플러그인 고치기
Codexe에서 만든 플러그인은 선택한 버전용으로 컴파일되고, 준비 완료 전에 올바른 plugin.yml이 있는지 확인돼요. 테스트 서버에서는 로그 탭이 오류를 강조해서 실시간으로 로그를 보여 주고, 로그 내보내기로 파일로 저장할 수 있어요. 프로젝트 채팅에 보이는 내용을 설명하면("/plugins에서 플러그인이 빨간색이고 로그에 ...라고 나와") Codexe가 코드를 바꾸고 다시 빌드해요. Codexe가 전달한 그대로의 파일에서 컴파일이 실패하면 AI로 고치기가 무료로 고쳐 줘요.
질문
서버 로그는 어디에 있나요?
현재 실행의 로그는 서버 폴더의 logs/latest.log에 있어요. 이전 실행의 로그는 같은 폴더에 .log.gz 파일로 있어요.
플러그인 하나가 다른 플러그인을 망가뜨릴 수 있나요?
네. 의존성이 빠지거나 망가지면 그게 필요한 모든 플러그인이 멈춰요. 다른 오류보다 로그의 첫 번째 오류부터 고치세요.
내 로그를 공유해도 안전한가요?
대체로 괜찮지만 먼저 확인하세요. 로그에는 IP 주소가, 일부 플러그인에서는 오류에서 나온 데이터베이스 비밀번호가 들어 있을 수 있어요.
망가진 플러그인을 내 서버용으로 다시 빌드하기
이 프롬프트는 바로 보낼 수 있는 상태로 열려요:
“더 이상 로드되지 않는 예전 플러그인을 대체하는 SimpleWarps라는 Paper 1.21.4 플러그인: 이름을 받는 /setwarp, /warp, /delwarp, /warps는 GUI로 목록 표시, 설정과 삭제에는 warps.admin 권한, 워프는 재시작 후에도 저장, 메시지는 config.yml에.”
Codexe로 이걸 생성하기