Hướng dẫn

Cách sửa lỗi plugin Minecraft

Cập nhật 18 tháng 10, 2026

Khi một plugin không nạp được, máy chủ gần như luôn cho biết lý do: nó nằm trong console lúc khởi động, vài dòng phía trên hoặc phía dưới tên plugin. Học cách đọc phần log đó và hầu hết lỗi chỉ mất một phút để sửa. Đây là những lỗi thường gặp và ý nghĩa của chúng.

Ghi phiên bản máy chủ của bạn và việc plugin cần làm.

Tạo thứ này với Codexe

Từng bước

1.Mở log của lần khởi động
Đọc console, hoặc logs/latest.log trong thư mục máy chủ. Trên bảng điều khiển hosting, hãy dùng console hoặc trình quản lý tệp của nó.
2.Tìm tên plugin
Tìm lỗi đầu tiên có nhắc đến nó. Những dòng bắt đầu bằng [ERROR] hoặc [WARN] kèm stack trace bên dưới là những dòng quan trọng.
3.Đọc dòng đầu tiên và các dòng "Caused by"
Dòng đầu tiên cho biết cái gì bị lỗi; dòng Caused by: cuối cùng thường cho biết vì sao. Những dòng có tên package của chính plugin cho biết lỗi nằm ở đâu trong mã của nó.
4.Đối chiếu với danh sách bên dưới
Hầu hết lỗi khởi động là do phiên bản, Java hoặc dependency, và thông báo lỗi cho biết là cái nào.
5.Sửa một thứ rồi khởi động lại
Thay đổi một thứ, khởi động lại (không phải /reload) và đọc lại log. Lỗi từ một plugin có thể gây ra lỗi ở các plugin khác.

Các lỗi thường gặp

Bạn thấy	Ý nghĩa	Cách sửa
`Unsupported API version 1.21`	`api-version` của plugin mới hơn máy chủ của bạn.	Lấy bản dành cho máy chủ của bạn, hoặc cập nhật máy chủ.
`Could not load 'plugins/X.jar'` kèm `Invalid plugin.yml` hoặc `Jar does not contain plugin.yml`	Tệp mô tả của plugin bị thiếu hoặc có lỗi YAML, hoặc tệp đó không phải plugin.	Kiểm tra bạn đã tải plugin chứ không phải mã nguồn, mod hay một tệp zip. Nếu bạn tự build, hãy sửa `plugin.yml`.
`UnsupportedClassVersionError`, "class file version 65.0"	Plugin cần Java mới hơn phiên bản máy chủ đang chạy (61 = Java 17, 65 = Java 21, 69 = Java 25).	Chạy máy chủ bằng Java đó, hoặc build lại plugin cho Java của bạn.
`NoClassDefFoundError` hoặc `ClassNotFoundException`	Một lớp mà plugin cần không có ở đó: thiếu một plugin dependency, một thư viện chưa được shade vào tệp .jar, hoặc API không tồn tại ở phiên bản này.	Cài plugin được nêu tên trong lỗi (Vault, ProtocolLib), hoặc dùng bản build cho phiên bản của bạn.
`Unknown/missing dependency plugins`	Một plugin ghi trong `depend` chưa được cài.	Cài nó vào `plugins/`.
`Error occurred while enabling X (Is it up to date?)`	Plugin đã nạp nhưng bị sập trong `onEnable`.	Đọc dòng `Caused by`: thường là lỗi cấu hình hoặc thiếu dependency.
`Ambiguous plugin name`	Có hai tệp .jar của cùng một plugin trong `plugins/`.	Xóa tệp cũ đi.

Những lỗi không liên quan đến việc nạp

Plugin màu xanh lá nhưng lệnh báo "Unknown command": lệnh không có trong plugin.yml, hoặc một plugin khác dùng cùng tên.
"I'm sorry, but you do not have permission": người chơi thiếu permission node. Xem trang của plugin để biết node và cấp nó bằng plugin phân quyền của bạn.
Lỗi sau khi sửa config.yml: YAML cần dấu cách, không phải tab, và cần dấu nháy quanh đoạn chữ bắt đầu bằng : hoặc &.
Chạy được sau khi khởi động lại, hỏng sau /reload: plugin không hỗ trợ /reload. Hãy khởi động lại thay vào đó.

Máy chủ của bạn cần Java nào

Minecraft 1.20.5 trở lên cần Java 21, còn 26.x cần Java 25; từ 1.18 đến 1.20.4 cần Java 17. Chạy java -version bằng đúng Java mà máy chủ dùng (trên bảng điều khiển hosting, đó thường là một thiết lập tên Docker image hoặc Java version). Plugin build cho Java cũ chạy được trên Java mới, nhưng không có chiều ngược lại.

Sửa plugin làm bằng Codexe

Plugin làm trên Codexe được biên dịch cho phiên bản bạn chọn và được kiểm tra có plugin.yml hợp lệ trước khi Sẵn sàng. Trên một máy chủ thử nghiệm, tab Nhật ký hiển thị log trực tiếp với các lỗi được tô sáng, và Xuất nhật ký lưu nó thành tệp. Mô tả những gì bạn thấy trong khung chat của dự án ("plugin có màu đỏ trong /plugins và log ghi ...") và Codexe sẽ sửa mã rồi build lại. Nếu Biên dịch thất bại trên các tệp đúng nguyên như Codexe đã giao, Sửa bằng AI sẽ sửa chúng miễn phí.

Câu hỏi

Log máy chủ nằm ở đâu?

logs/latest.log trong thư mục máy chủ, cho lần chạy hiện tại. Các lần chạy trước nằm trong cùng thư mục dưới dạng tệp .log.gz.

Một plugin có thể làm hỏng plugin khác không?

Có: một dependency bị thiếu hoặc bị hỏng sẽ chặn mọi plugin cần nó. Hãy sửa lỗi đầu tiên trong log trước các lỗi khác.

Chia sẻ log của tôi có an toàn không?

Phần lớn là an toàn, nhưng hãy kiểm tra trước: log có thể chứa địa chỉ IP và, với một số plugin, mật khẩu cơ sở dữ liệu trong thông báo lỗi.

Build lại một plugin bị hỏng cho máy chủ của bạn

Prompt này mở ra sẵn sàng để gửi:

“Một plugin Paper 1.21.4 tên SimpleWarps thay thế plugin cũ không còn nạp được của tôi: /setwarp, /warp và /delwarp với một cái tên, /warps liệt kê chúng trong một GUI, quyền warps.admin để đặt và xóa, warp được giữ qua các lần khởi động lại, tin nhắn trong config.yml.”