Minecraft “Could Not Load Plugin” Hatası Çözümü

“Could not load plugin” hatası, sunucunun plugins klasöründeki bir jar dosyasını okuyup etkinleştiremediğini söyler; ama o satır tek başına nedeni açıklamaz. Nedeni hemen altındaki ikinci satır yazar. Bu sayfadan tek bir şey aklınızda kalacaksa şu olsun: ilk satır hangi eklentinin yüklenmediğini, ikinci satır neden yüklenmediğini söyler. Teşhis her zaman ikinci satırdan başlar.

Aşağıda Paper 26.2 üzerinde karşılaşacağınız bütün senaryoları gerçek log metinleriyle sıraladım: eksik bağımlılık, geçersiz plugin.yml, uyumsuz api-version, yanlış Java sürümü ve 26.1 ile gelen unobfuscation kırılması. Sonunda da suçlu eklentiyi beş yeniden başlatmada bulmanızı sağlayan sistematik bir yöntem var.

Hata Satırını Doğru Okumak#

PaperMC’nin resmî dokümanındaki örnek log bloğu şöyledir. İki satırın da tam olarak ne söylediğine dikkat edin:

[00:00:00] [Server thread/WARN] Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins'
[00:00:00] [Server thread/WARN] org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'.

Birinci satır her senaryoda aynıdır; ikinci satır değişir ve çözümü belirler. Karşılaşacağınız üç ana istisna tipi şunlardır:

Hatayı bulmak için tüm logu okumanıza gerek yok. Açılışın ilk 30 saniyesi yeterlidir:

grep -nE "Could not load|Exception|api-version|Legacy plugin" logs/latest.log | head -40

Select-String -Path .\logs\latest.log -Pattern "Could not load|Exception|Legacy plugin" | Select-Object -First 40

Log biçiminin tamamını ve hangi uyarıların önemsiz olduğunu sunucu logu okuma rehberinde bulabilirsiniz.

Neden 1: Eksik Bağımlılık#

En sık ve en kolay çözülen senaryo budur. Bazı eklentiler ekonomi, yetki veya değişken işini kendileri yapmaz; başka bir eklentinin API’sini kullanır. Bağımlılık yoksa sunucu eklentiyi hiç yüklemez. Köşeli parantez içindeki isim size ne kuracağınızı doğrudan söyler.

org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'.

Türkçe sunucularda en sık istenen üç bağımlılık şunlardır:

Vault / VaultUnlocked

Ekonomi, yetki ve sohbet API’lerini birleştiren köprü. Orijinal Vault 1.7.3 sürümünde kaldı; 26.x sunucularında geriye dönük uyumlu modern çatal olan VaultUnlocked tercih edilir.

PlaceholderAPI

Eklentiler arası değişken (placeholder) altyapısı. 26.2’ye çıkan sunucular 2.12.3 sürümüne güncellemek zorundadır; Paper 26.2 sürüm dizgisini değiştirdiği için eski yapılar açılışta düşer.

WorldEdit

WorldGuard’ın zorunlu ön koşuludur. WorldGuard 7.0.18 kurmuş ama WorldEdit’i unutmuşsanız bu hatayı alırsınız.

Bağımlılık eklentilerinin ne işe yaradığını ve nasıl yapılandırıldığını Vault ve PlaceholderAPI sayfasında ayrıntılı anlattım.

Neden 2: Geçersiz plugin.yml (Aslında Eklenti Değil)#

İkinci satırda InvalidDescriptionException görüyorsanız jar dosyasının içinde geçerli bir plugin.yml yok demektir. Bunun iki klasik sebebi vardır.

Birincisi: indirdiğiniz şey eklenti değil, mod. Modrinth ve CurseForge’da aynı isimle hem Fabric/Forge modu hem Bukkit eklentisi bulunabilir. Modların içinde plugin.yml yerine fabric.mod.json veya META-INF/mods.toml bulunur ve Paper bunları yükleyemez. İndirme sayfasında “Paper”, “Spigot” veya “Bukkit” etiketini kontrol edin.

İkincisi: indirme yarıda kalmış. Bazı siteler doğrudan dosya yerine bir yönlendirme veya hata sayfası döndürür ve tarayıcı bunu jar adıyla kaydeder. Kontrolü şöyle yapabilirsiniz:

# Jar gercekten bir arsiv mi ve plugin.yml iceriyor mu?
unzip -l plugins/OrnekEklenti.jar | grep -E "plugin.yml|fabric.mod.json|mods.toml"

# Dosya boyutlari (birkac KB'lik jar neredeyse kesin bozuk)
ls -lh plugins/*.jar

Panel üzerinden çalışıyorsanız yükleme sırasında dosyanın gerçekten kök dizine düştüğünü panelden plugin yükleme adımlarına bakarak doğrulayın.

Neden 3: API Sürümü Uyumsuzluğu#

Her modern eklentinin plugin.yml dosyasında api-version alanı bulunur ve eklentinin hangi Bukkit API kuşağı için derlendiğini söyler. Paper bu değeri açılışta kontrol eder ve üç farklı sonuç üretir.

Desteklenmeyen API sürümü#

Eklentinin belirttiği API sürümü sunucunun tanıdığı aralıkta değilse yükleme reddedilir:

org.bukkit.plugin.InvalidPluginException: Unsupported API version 1.21

Çözüm ikiden fazla değildir: ya sunucuyu eklentinin istediği sürüme çıkarın ya da eklentinin sunucunuza uyan dağıtımını indirin. Sürüm karışıklığı yaşamamak için Minecraft’ın yeni sürüm numaralandırmasını bilmek işinizi kolaylaştırır: 26.1 protokol 775, 26.2 ise protokol 776 kullanır ve ikisi de Java 25 ister.

Minimum API sınırının altında kalmak#

org.bukkit.plugin.InvalidPluginException: Plugin API version <X> is lower than the minimum allowed version. Please update or replace it.

Bu mesaj bukkit.yml içindeki settings.minimum-api ayarıyla ilgilidir. Sunucu, belirlediğiniz eşiğin altındaki eklentileri kabul etmez. Eski bir eklentiyi bilerek çalıştırmak istiyorsanız eşiği düşürebilirsiniz, ancak bu tercihi bilinçli yapın:

# bukkit.yml
settings:
  minimum-api: none
  allow-end: true

api-version hiç belirtilmemiş#

[WARN]: Legacy plugin <PluginAdi vX.Y> does not specify an api-version.

Bu bir hata değil uyarıdır; eklenti yüklenir ama eski (legacy) uyumluluk modunda çalışır. Yıllardır güncellenmemiş bir eklenti kullandığınızın işaretidir. Böyle eklentiler 26.x’te ileride sessiz sorunlar çıkarabilir; mümkünse hâlâ bakımı yapılan bir alternatifle değiştirin.

Neden 4: Java Sürümü Uyuşmazlığı#

Bu hata bazen sunucunun kendisinde, bazen tek bir eklentide ortaya çıkar. Metin uzundur ama içindeki iki sayı her şeyi söyler:

java.lang.UnsupportedClassVersionError: net/minecraft/bundler/Main has been compiled by a more recent version of the Java Runtime (class file version 69.0), this version of the Java Runtime only recognizes class file versions up to 65.0

“Compiled by” kısmındaki numara dosyanın hangi Java ile derlendiğini, “only recognizes up to” kısmındaki numara sizin kurulu Java’nızı gösterir. Eşleme tablosu şudur:

Kurulu sürümü doğrulayın ve gerekiyorsa Java 25 LTS’e çıkın:

java -version

Bir eklenti Java 25 ile derlenmiş ama sunucunuz Java 21’de çalışıyorsa o eklenti “Could not load” ile değil doğrudan UnsupportedClassVersionError ile düşer. Ayrıntı ve sürüm eşleştirme tablosunun tamamı için Java sürüm hatası sayfasına bakın.

Neden 5: 26.1 Unobfuscation Kırılması#

Bu bölüm sayfanın en kritik kısmı, çünkü belirtisi ötekilere hiç benzemez. Minecraft 26.1 ile Mojang obfuscated sunucu jar’ı yayınlamayı bıraktı; sunucu jar’ı artık gerçek sınıf, metot ve alan adlarını içeriyor. Paper bunun üzerine dahili remapper’ını tamamen kaldırdı, Spigot düşürdü, Fabric de Yarn’dan Mojang Mappings’e geçti.

Tipik çalışma zamanı hataları şöyle görünür:

java.lang.NoSuchMethodError: 'org.bukkit.attribute.Attribute org.bukkit.craftbukkit.attribute.CraftAttribute.minecraftToBukkit(...)'
java.lang.NoClassDefFoundError: net/minecraft/server/v1_XX_RX/...

Bu satırları logs/latest.log içinde eklenti adıyla birlikte görürsünüz; yığın izinin okunması crash report okuma rehberinde anlatıldı. Çözüm tek: o eklentinin 26.x için yayınlanmış sürümünü kurmak. Geliştirici 26.x sürümü çıkarmadıysa eklentiyi değiştirmekten başka yol yoktur; eski jar’ı zorlamak sunucuyu istikrarsızlaştırır.

Henüz 1.21.11’deyseniz ve 26.2’ye geçmeden önce hangi eklentilerin kırılacağını öğrenmek isterseniz, remapper’ı kapatarak önden test edebilirsiniz:

java -Dpaper.disablePluginRemapping=true -jar paper-1.21.11.jar --nogui

Bu bayrakla açılışta düşen veya oyun içinde hata veren eklentiler, 26.x’e geçtiğinizde de düşecek olanlardır. Sürüm yükseltme planınızı bu listeye göre yapın.

26.2 Uyumluluğu: Popüler Eklentilerin Durumu#

Sunucu 26.2’ye çıktığında eklentilerin bir kısmı otomatik uymaz. Yaygın kullanılanların 2026 Ağustos itibarıyla durumu:

Suçlu Eklentiyi Bulma: İkiye Bölme Yöntemi#

Log net bir isim vermiyorsa ya da birden fazla eklenti aynı anda sorun çıkarıyorsa tahmin yürütmeyin. İkiye bölerek arama, 20 eklentili bir sunucuda suçluyu ortalama 5 yeniden başlatmada bulur.

1. Geçici bir klasör oluşturun#

   plugins klasörünün dışında bir yer seçin; içinde açtığınız klasör zaten taranmaz ama karışıklık olmasın.

   mkdir -p ~/eklenti-test

2. Eklentilerin yarısını taşıyın#

   Alfabetik listenin ilk yarısını taşıyın. Bağımlılıkları (Vault, PlaceholderAPI, WorldEdit) taşıdığınız yarıya denk gelirse onlara bağlı eklentileri de birlikte taşıyın, yoksa yanıltıcı bağımlılık hatası alırsınız.

3. Sunucuyu başlatıp logu okuyun#

   Hata devam ediyorsa suçlu plugins klasöründe kalanlar arasındadır. Hata kaybolduysa taşıdıklarınız arasındadır.

4. Kalan yarıyı tekrar ikiye bölün#

   Aynı işlemi suçlunun bulunduğu tarafta yineleyin. Her turda aday sayısı yarıya iner.

5. Tek eklenti kalınca doğrulayın#

   Şüpheliyi tek başına yükleyip sunucuyu başlatın. Hata yeniden çıkıyorsa teşhis kesindir; eklentinin güncel sürümünü arayın veya kaldırın.

Yükleme Sorunlarını Baştan Önlemek#

Eklenti hatalarının büyük çoğunluğu üç alışkanlıkla ortadan kalkar. Birincisi eklentileri yalnızca resmî dağıtım kanallarından indirmek: Hangar, Modrinth, SpigotMC ve geliştiricinin kendi sitesi. Ücretli eklentilerin “bedava” dağıtıldığı forumlardan indirilen jar dosyaları hem çalışmaz hem de sunucu güvenliğiniz için ciddi risktir.

İkincisi tek seferde tek değişiklik yapmak. Beş eklentiyi aynı anda ekleyip sunucuyu başlatırsanız hangi jar’ın soruna yol açtığını bulmak zorlaşır. Yeni eklentiyi ekleyin, başlatın, logu okuyun, sonra sonrakine geçin.

Üçüncüsü sürüm disiplini. Sunucu sürümünüzü sabit tutun ve her eklentinin indirme sayfasında o sürümün etiketini arayın. Kurulum akışının tamamını plugin kurulumu rehberinde bulabilirsiniz. Eklentileri barındıran sunucunun kendisi de belirleyicidir: 8 GB RAM, Ryzen 9 işlemci ve NVMe SSD üzerinde çalışan bir Minecraft sunucu paketi açılış sürelerini kısaltır ve eklenti yüklenirken oluşan zaman aşımı kaynaklı ikincil hataları önler.

Özetle#

“Could not load plugin” hatasında çözüm her zaman ikinci satırdadır. UnknownDependencyException eksik eklentiyi, InvalidDescriptionException yanlış dosyayı (genellikle mod veya yarım indirme), Unsupported API version sürüm uyumsuzluğunu, UnsupportedClassVersionError ise yanlış Java’yı işaret eder.

26.x sunucularında ek olarak bir tuzak var: unobfuscation nedeniyle kırılan eklentiler açılışta hata vermez, çalışma anında NoSuchMethodError ile patlar. Bu yüzden 26.2’ye geçmeden önce eklenti listenizi tek tek 26.x etiketiyle doğrulayın, jar’ları yalnızca resmî kaynaklardan indirin ve değişiklikleri teker teker uygulayın. Çözemediğiniz bir hata kalırsa log’un ilgili bölümüyle birlikte destek talebi açabilir, benzer sorunlar için sunucu hataları rehberine göz atabilirsiniz.