Modlu Minecraft Sunucusu Hataları ve Çözümleri

Modlu Minecraft sunucusu hataları göründüğünden çok daha dar bir kümede toplanır: yanlış Java sürümü, eksik ya da sürümü tutmayan bir mod, yetersiz bellek ve yanlış başlatma komutu. Konsolda uzun bir Java yığın izi (stack trace) görmek korkutucudur ama o metnin içinde neredeyse her zaman tek satırlık, apaçık bir suçlu vardır. Bu sayfa o satırı nasıl bulacağınızı ve her hata tipinde tam olarak ne yapmanız gerektiğini adım adım anlatır.

Anlatım hem Windows hem Linux sunucular için geçerlidir; işletim sistemine özel kurulum adımları için VDS üzerinde modlu sunucu kurma rehberine göz atabilirsiniz. Sayfadaki tüm örnekler Minecraft 26.2 "Chaos Cubed" ve Java 25 dönemine göre yazılmıştır.

Önce doğru dosyayı açın: latest.log, debug.log ve crash-reports#

Hata çözümüne panelin konsol penceresine bakarak başlamayın; konsol geriye doğru kaydırıldığında ilk hatayı kaybedersiniz. Sunucu klasöründe üç yer vardır:

logs/latest.log

Son açılışın tam kaydı. Teşhisin %90’ı buradadır.

logs/debug.log

Daha ayrıntılı kayıt. NeoForge destek ekibi genellikle bu dosyayı ister.

crash-reports/

crash-2026-08-18_14.22.05-server.txt biçiminde dosyalar. Yalnızca çöküş anının fotoğrafı; yığın izi ve yüklü mod listesi burada.

Dosyayı açtıktan sonra en alta gitmeyin, ilk ERROR veya FATAL satırını arayın. Sonraki onlarca satır çoğu zaman ilk hatanın devamıdır. Linux sunucuda hızlı arama için:

cd /opt/minecraft/sunucu
grep -n -m 5 -E "ERROR|FATAL|Caused by" logs/latest.log
grep -n "Missing or unsupported" logs/latest.log
tail -n 120 logs/latest.log

Windows tarafında aynı işi PowerShell ile yaparsınız:

Select-String -Path "C:\minecraft\sunucu\logs\latest.log" -Pattern "ERROR","FATAL","Caused by" | Select-Object -First 5
Get-Content "C:\minecraft\sunucu\logs\latest.log" -Tail 120

Çöküş dosyasının yapısını ve hangi bölümün ne anlattığını ayrıntılı olarak crash report okuma rehberinde bulabilirsiniz.

Sunucu hiç açılmıyor: Java sürümü uyuşmuyor#

Modlu sunucuda en sık karşılaşılan ilk engel budur. Konsol tek satır hata verip kapanır:

Error: LinkageError occurred while loading main class net.minecraft.server.Main
java.lang.UnsupportedClassVersionError: net/minecraft/server/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

Bu mesaj "sunucu senin kurduğundan daha yeni bir Java ile derlendi" demektir. Class file 69.0 Java 25’e, 65.0 Java 21’e karşılık gelir. Çözüm modu kaldırmak değil, doğru Java’yı kurmaktır. Önce hangi Java’nın çalıştığını doğrulayın:

java -version
# beklenen çıktı: openjdk version "25.0.4" ...

Java kurulumunu tamamladıktan sonra hatanın tüm varyantlarını UnsupportedClassVersionError çözüm sayfasından kontrol edebilirsiniz.

“Missing or unsupported mandatory dependencies” — eksik bağımlılık#

Forge ve NeoForge, modları yüklemeden önce bağımlılıkları sıralar. Bir mod başka bir modu istiyor ve o mod yoksa (ya da sürümü tutmuyorsa) sunucu hiç başlamaz ve şu blok yazılır:

[main/ERROR] [ne.mi.fm.lo.ModSorter/LOADING]: Missing or unsupported mandatory dependencies:
    Mod ID: 'jei', Requested by: 'examplemod', Expected range: '[19.0,)', Actual version: [MISSING]
    Mod ID: 'neoforge', Requested by: 'ornekmod', Expected range: '[26.2,)', Actual version: '26.1.2.95'

Bu satırlar dört bilgi verir ve dördü de çözümü doğrudan söyler:

• Mod ID — eksik olan modun kimliği (jei).
• Requested by — onu isteyen mod (examplemod).
• Expected range — istenen sürüm aralığı ([19.0,) = 19.0 ve üzeri).
• Actual version — kurulu sürüm. [MISSING] ise mod hiç yok demektir.

Çözüm iki seçenekten biridir: eksik modu mods/ klasörüne doğru sürümüyle ekleyin ya da onu isteyen modu kaldırın. Sürüm aralığı tutmuyorsa mevcut jar’ı silip beklenen aralıktaki yapıyı indirin. Mod dosyalarını ekleyip çıkarma sırasında dünyayı bozmamak için mod ekleme ve çıkarma rehberindeki sırayı izleyin.

Fabric’teki karşılığı: “Incompatible mod set!”#

Fabric aynı sorunu bağlantı anında değil, sunucu açılırken çözümleme aşamasında bildirir ve çok değerli bir şey yapar: çözümü kendisi yazar.

Incompatible mod set!
net.fabricmc.loader.impl.FormattedException: Mod resolution encountered an incompatible mod set!
A potential solution has been determined:
    - Replace mod 'Fabric API' (fabric-api) 0.152.0 with version 0.157.0 or later.
Unmet dependency listing:
    - Mod 'Ornek Mod' (ornekmod) 1.4.2 requires version 0.157.0 or later of fabric-api

A potential solution has been determined: satırının altındaki cümleyi harfiyen uygulayın; Fabric hangi modu hangi sürüme çekmeniz gerektiğini isim ve numarayla söyler. Fabric modlarının neredeyse tamamı Fabric API’ye bağımlıdır; 26.2 için güncel sürüm 0.157.0+26.2’dir.

“Mixin apply failed” ve 26.1 sonrası eski mod jar’ları#

Mixin, bir modun Minecraft’ın mevcut bir metoduna kod enjekte etmesidir. FAILED during APPLY hatası, modun hedeflediği metodun o sürümde artık bulunmadığı anlamına gelir:

Caused by: org.spongepowered.asm.mixin.throwables.MixinApplyError: Mixin
[ornekmod.mixins.json:chunk.LevelRendererMixin from mod ornekmod] from phase [DEFAULT]
in config [ornekmod.mixins.json] FAILED during APPLY

Üç nedeni vardır: (a) mod o Minecraft sürümü için derlenmemiştir, (b) başka bir mod aynı hedef metodu değiştirmiştir, (c) mod sürümü eskidir. 2026’da en sık görülen neden birincisidir ve nedeni tek bir tarihsel olaydır:

Minecraft 26.1 obfuscated varyantı olmayan ilk sürümdür. Bu bir ABI kırılmasıdır; 1.21.11 ve öncesi için derlenmiş hiçbir mod yeniden derlenmeden 26.x üzerinde çalışmaz.

Pratikte bu şu demektir: "26.2’ye güncelledim, mods/ klasörünü olduğu gibi taşıdım" senaryosu çalışmaz. Her modun 26.2 için yayınlanmış ayrı yapısını indirmeniz gerekir. Eski jar’lar tipik olarak şu üç hatadan biriyle patlar: MixinApplyError, NoSuchMethodError, NoClassDefFoundError.

Forge ve NeoForge sunucusu başlamıyor: run betiği ve unix_args.txt#

Forge 1.17 ve sonrasında çalıştırılabilir tek bir forge-<surum>.jar sunucu jar’ı artık yoktur. Installer bunun yerine şu dosyaları üretir:

sunucu-klasoru/
 |-- user_jvm_args.txt      <-- RAM ve JVM ayarları BURADA
 |-- run.sh                 <-- Linux başlatma betiği
 |-- run.bat                <-- Windows başlatma betiği
 |-- libraries/             <-- tüm bağımlılıklar ve arg dosyaları
 |-- mods/
 |-- eula.txt
 +-- server.properties

Eski alışkanlıkla java -jar forge-26.2-65.1.2.jar nogui yazarsanız sunucu açılmaz. Doğru başlatma run.sh (Linux) veya run.bat (Windows) üzerinden yapılır. Bu betikler user_jvm_args.txt dosyasını @user_jvm_args.txt söz dizimiyle okur; dolayısıyla RAM ayarını da o dosyaya yazarsınız:

# user_jvm_args.txt (16 GB paket için)
-Xms14G
-Xmx14G
-XX:+UseG1GC
-XX:+ParallelRefProcEnabled
-XX:MaxGCPauseMillis=200
-XX:+AlwaysPreTouch
-XX:MaxMetaspaceSize=1g

Panel üzerinde çalışıyorsanız sık görülen bir hata daha vardır. Pterodactyl run.sh çalıştırmaz; başlatma komutunda kök dizindeki unix_args.txt dosyasını arar. Bu dosya aslında libraries/ altındadır ve egg kurulum betiği köke sembolik bağ atar. Bağ oluşmamışsa konsolda şunu görürsünüz:

Error: Could not find or load main class @user_jvm_args.txt

Elle düzeltmek için sunucu kökünde bağı yeniden kurun:

# Forge
ln -sf libraries/net/minecraftforge/forge/*/unix_args.txt unix_args.txt

# NeoForge
ln -sf libraries/net/neoforged/neoforge/*/unix_args.txt unix_args.txt

Panelde çalışan modlu sunucularda bu adımın tamamı ve doğru egg seçimi için Pterodactyl’de modlu sunucu kurma sayfasını okuyun.

Bellek hataları: heap, Metaspace ve Watchdog#

Modlu sunucuda "RAM yetmiyor" tek bir hata değildir; üç ayrı olay aynı isimle karıştırılır. Hangisi olduğunu mesajın devamındaki kelime söyler.

Metaspace kısmı özellikle önemlidir çünkü internetteki rehberlerin çoğu yanlış anlatır: Metaspace heap dışıdır, -Xmx’e dahil değildir. Bu hatada -Xmx’i artırmak konteynerli bir sunucuda durumu kötüleştirir, çünkü konteyner limiti heap + Metaspace + native belleğin toplamını sayar.

Watchdog uyarısında konsol [FATAL]: A single server tick took 60.00 seconds (should be max 0.05) yazar ve ardından tam bir iş parçacığı dökümü basar. O dökümde en üstteki mod paket adı (örneğin com.ornek.mod.…) suçluyu gösterir. max-tick-time=-1 yaparak Watchdog’u kapatmak son çaredir ve sorunu çözmez, sadece gizler. Bellek hatalarının tüm varyantları için Out of Memory hatası çözüm sayfasına, doğru paket seçimi için modlu sunucu RAM hesabına bakın.

Sunucu açılıyor ama oyuncular giremiyor#

Sunucu konsolu Done yazdığı hâlde oyuncular bağlanamıyorsa hata artık sunucu tarafında değil, istemci-sunucu el sıkışmasındadır. En sık üç mesaj görülür:

• Kırmızı X ve "Incompatible FML modded server" — sunucu listesinde çıkan bir ipucu; mod listesi, ağ kanalları veya registry uyuşmuyor.
• "Your client is missing the following mods…" — istemcide eksik mod var, tablo hangi modun hangi sürümde gerektiğini gösterir.
• "Connection closed - mismatched mod channel list" — iki tarafın kayıtlı ağ kanalı listesi birebir aynı değil.

Bu üç mesajın ayrımı ve kalıcı çözümü ayrı bir sayfada, mod uyuşmazlığı hatası rehberinde ele alınıyor. Oyuncu tarafındaki launcher ve modpack sürümü adımları içinse modlu sunucuya arkadaş bağlama sayfası daha uygun.

Bir de modlu sunuculara özel bir bağlantı hatası vardır: büyük paketlerde yapılandırma ve registry senkronizasyonu tek paket sınırını aşabilir.

Internal Exception: io.netty.handler.codec.DecoderException:
java.lang.IllegalArgumentException: Payload may not be larger than 1048576 bytes

Bu mesajda çözüm ağ ayarı değil, paket içeriğini küçültmektir: gereksiz büyük yapılandırma dosyalarını sadeleştirin, çok sayıda tarif/registry ekleyen modları gözden geçirin. Netty kaynaklı diğer kopmalar için Internal Exception hatası sayfasına bakabilirsiniz.

Sunucu açılıyor ama sürünüyor#

Konsolda Can’t keep up! Is the server overloaded? uyarısı çıkıyorsa bu bir hata değil, performans sorunudur. Modlu sunucuda ilk bakılacak üç şey şudur: yetersiz heap, tek çekirdek performansı düşük işlemci ve dünya üretiminin canlı yapılması.

Minecraft’ın ana tick döngüsü tek çekirdekte çalışır; bu yüzden çekirdek sayısı değil saat hızı belirleyicidir. Modlu sunucu için Ryzen 9 7900X / 7950X sınıfı yüksek frekanslı işlemci, 16 GB’dan başlayan RAM ve 100 GB üzeri NVMe SSD gerekir. Batihost’un modlu Minecraft sunucu paketleri bu yapılandırmayla teslim edilir.

Hangi modun yavaşlattığını tahmin etmek yerine ölçün. spark modunu kurup şu komutları çalıştırın:

/spark tps
/spark health --memory
/spark profiler start --timeout 300 --only-ticks-over 100
/spark profiler stop
/spark heapsummary --run-gc-before

heapsummary çıktısı hangi mod sınıfının kaç MB tuttuğunu gösterir; yani "RAM’i hangi mod yiyor" sorusunun ölçülmüş cevabıdır. Ayrıntılı okuma için spark ve timings analizi sayfasına, kalıcı iyileştirmeler için modlu sunucu optimizasyonu rehberine geçin.

Hata çözümünde izlenecek sıra#

1. Yedek alın#

   Hiçbir şeye dokunmadan önce world/, mods/ ve config/ klasörlerini birlikte tarihli bir klasöre kopyalayın. Üçünü ayrı ayrı değil birlikte yedekleyin; dünyayı geri yüklerken mod ve yapılandırma sürümlerinin uyuşması gerekir.

   save-all
   save-off
   # sunucuyu durdurun, sonra:
   cp -a world mods config /yedek/batihost-2026-08-18/

2. İlk hata satırını bulun#

   logs/latest.log dosyasında ilk ERROR veya Caused by: satırını okuyun. Sonraki yüzlerce satır genellikle aynı hatanın devamıdır.

3. Java sürümünü doğrulayın#

   java -version çıktısı Minecraft sürümünüzle eşleşiyor mu bakın. 26.x için Java 25 dışında bir şey görüyorsanız önce bunu düzeltin.

4. Mod listesini sadeleştirin#

   Şüpheli modu ikiye bölme yöntemiyle bulun. Bulduğunuz modu güncelleyin ya da kaldırın, sunucuyu boş dünyayla test edin.

5. Bellek ve başlatma komutunu kontrol edin#

   user_jvm_args.txt içindeki -Xms ve -Xmx eşit mi, konteyner limitinin altında mı bakın. Ardından sunucuyu run.sh / run.bat ile başlatın.

6. Hâlâ çözülmediyse kaydı paylaşın#

   latest.log ve varsa crash-reports/ dosyasını ekleyerek destek talebi açın. Ekran görüntüsü değil, ham log dosyası gönderin.

Özetle#

Modlu sunucu hataları tahminle değil kayıtla çözülür. logs/latest.log dosyasındaki ilk hata satırı size neredeyse her zaman doğrudan suçluyu söyler: yanlış Java sürümü, eksik bağımlılık modu, eski derlenmiş bir jar ya da yetersiz heap. Minecraft 26.1 ile gelen unobfuscation nedeniyle eski mod dosyalarının 26.x’te çalışmadığını unutmayın; sürüm geçişinde mods/ klasörünü taşımak yerine her modun yeni yapısını indirin.

Donanım tarafında modlu sunucu için taban 16 GB RAM, yüksek saat hızlı Ryzen 9 işlemci ve NVMe SSD gerekir; büyük paketlerde 24-32 GB’a çıkmanız gerekebilir. Kurulumu sıfırdan yapmak istiyorsanız modlu sunucu kurulum rehberiyle başlayın; sunucuya istemci paketini değil daima server pack’i yükleyin.