Sorun Giderme

Kurulum sırasında ya da ilk günlerde bir şeyler ters gitmişse büyük ihtimalle jekcms hatası değil, sunucu yapılandırmasından kaynaklanan bir uyumsuzluktur. Bu sayfa belirtiye göre gezmek üzere tasarlandı: siz neyi görüyorsanız ilgili başlığa atlayın, sebep ne, çözüm ne — üçünü birlikte okuyun.

Aşağıdakilerden hiçbiri uymuyorsa ilk bakacağınız yer logs/php-errors.log dosyası. jekcms fatal hataların neredeyse tamamını oraya yazar, genelde sorunun kaynağı bir-iki satırda görünür.

500 Internal Server Error

Belirti: Yükleyici dahil her sayfa 500 Internal Server Error döndürüyor.

Olası neden: Apache .htaccess dosyasını işleyemiyor. Ya mod_rewrite devre dışı ya da vhost'ta AllowOverride None yazıyor.

Çözüm:

sudo a2enmod rewrite && sudo systemctl restart apache2

Sonra vhost dosyanızı (/etc/apache2/sites-available/000-default.conf gibi) açıp web kökünüz için <Directory> bloğu içinde AllowOverride All yapın.

Veritabanı "Connection refused"

Belirti: Yükleyicinin 2. adımı SQLSTATE[HY000] [2002] Connection refused hatasıyla düşüyor.

Olası neden: MySQL beklediğiniz portu dinlemiyor ya da güvenlik duvarı engelliyor. Lokal kurulumlarda genelde Unix soketi ile TCP arasındaki uyuşmazlıktan kaynaklanır.

Çözüm: DB host alanına localhost yerine 127.0.0.1 yazın. localhost PHP'yi Unix soketine yönlendiriyor, 127.0.0.1 TCP'yi zorluyor. Sunucu gerçekten uzaktaysa 3306 portunun açık olduğundan emin olun:

sudo ufw allow from <webserver-ip> to any port 3306

Giriş sonsuz döngüye giriyor

Belirti: Admin girişi başarılı oluyor, sonra hemen giriş ekranına geri atıyor.

Olası neden: Oturum çerezleri saklanamıyor. En sık sebepler: alan adı uyumsuzluğu (example.com ile www.example.com farklı), PHP oturum klasörünün yazılamaz olması veya admin URL'si ile kanonik URL arasında sondaki eğik çizgi farkı.

Çözüm:

sudo chmod 1733 /var/lib/php/sessions

Ve config/config.php içindeki SITE_URL değerini kullanıcının adres çubuğuna yazdığı biçimle (www var mı yok mu) birebir aynı yapın.

Boş admin sayfası

Belirti: Beyaz sayfa, kaynak kodu boş, tarayıcı hata göstermiyor.

Olası neden: display_errors kapalıyken bir PHP fatal hatası oluşmuş. Genelde tema ya da eklentinin ihtiyaç duyduğu bir PHP eklentisi sunucuda yok.

Çözüm: Hata logunun son satırlarına bakın:

tail -n 50 logs/php-errors.log

Son satır hata veren sınıf veya fonksiyonun adını verir — eksik eklenti genelde gd, imagick ya da intl olur. Onu kurduğunuzda sayfa düzelir.

Görsel yüklenmiyor

Belirti: Medya kütüphanesinde yükleme çubuğu dolar gibi olur, sonunda Upload failed çıkar.

Olası neden: uploads/ klasörüne web sunucusu kullanıcısı yazma izni yok.

Çözüm:

sudo chown -R www-data:www-data uploads/ && sudo chmod -R 755 uploads/

Paylaşımlı hosting'deyseniz ve root yetkiniz yoksa cPanel veya Plesk'in dosya yöneticisinden uploads/ izinlerini 755 yapın.

Öne çıkarılan görsel kırık görünüyor

Belirti: Yazı açılıyor ama öne çıkarılan görsel kırık ikon. URL incelendiğinde https://siteniz.com/uploads/2026/04/gorsel.webp 404 veriyor.

Olası neden: config/config.php içindeki UPLOADS_URL ile gerçek uploads/ klasörü arasındaki eşleşme bozulmuş. Kurulumu alt dizine taşımak veya CDN arkasına almak bu durumu sık yaratıyor.

Çözüm: config/config.php dosyasını açıp şu iki tanımı düzenleyin:

define('UPLOADS_URL', SITE_URL . '/uploads');
define('UPLOADS_PATH', __DIR__ . '/../uploads');

Ardından önbelleği temizleyin:

rm -rf cache/*

"Security validation failed"

Belirti: Her admin form gönderimi Security validation failed. Please reload and try again. hatasıyla düşüyor.

Olası neden: CSRF token uyumsuzluğu. Ya oturumun süresi dolmuş ya da aynı anda iki admin sekmesi açık ve yenisi eskisinin token'ını geçersiz kılmış.

Çözüm: Önce Ctrl+R ile sayfayı yenileyin. Bu tekrarlıyorsa oturum ömrünüz çok kısadır — config/config.php içindeki SESSION_LIFETIME değerini 7200 (2 saat) yapın.

Tema değiştirdim, ön yüz beyaz

Belirti: Yeni bir tema etkinleştirildi, ön yüz artık bomboş beyaz sayfa.

Olası neden: Tema arşivinde gerekli bir şablon (tipik olarak index.php veya single.php) eksik.

Çözüm: CLI'dan önceki temaya geri dönün:

php cli.php theme:activate default

Sonra uygulamaya çalıştığınız temayı gözden geçirin — en azından index.php, single.php, page.php ve style.css dosyalarına ihtiyacı var.

AI asistanı "Invalid API key" veriyor

Belirti: OpenAI destekli özellikler — içerik asistanı, SEO önerileri — 401 Invalid API key dönüyor, oysa anahtarı OpenAI playground'da denediğinizde çalışıyor.

Olası neden: Anahtarın sonuna boşluk veya satır sonu kaçmış. Terminalden kopyala-yapıştırlarda sıkça olur.

Çözüm: Settings → API Keys → OpenAI → Edit. Anahtarı silip özenle yeniden yapıştırın, kaydedin. 2026-01'den sonraki sürümler yeni girişleri otomatik trim ediyor ama eski kurulumlarda boşluk hâlâ yapışabiliyor.