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.

!Hata günlüğü ekranı: dosya seçici ve Son 30 satırı kopyala düğmesi

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.

Giriş formu, doğru olduğunu bildiğiniz parolayı reddediyor

Belirti: Bilgiler doğru, hesap etkin, ama giriş ekranı Geçersiz e-posta veya parola demeye devam ediyor.

Olası sebep: iki bot önleminden biri - ve ikisi de ekranda bunu söylemiyor.

Formda boş kalması gereken bir bal kabı alanı var. Betikler görür, insanlar görmez; dolayısıyla bu yalnız otomatik girişleri ısırır - her alanı dolduran bir tarayıcı eklentisi ya da genel bir seçici kullanan bir test betiği onu doldurur ve reddedilir.

Form ayrıca ne zaman oluşturulduğunu kaydeder ve iki saniyeden kısa sürede yapılan gönderimleri reddeder. Anında gönderen bir parola yöneticisi buna takılabilir.

Çözüm: formu normal biçimde, yüklendikten bir an sonra gönderin. Girişi otomatikleştiriyorsanız yalnız kullanıcı adı ve parola alanlarını hedefleyin, gerisine dokunmayın.

Lisans sözleşmesi ekranı devam etmeye izin vermiyor

Belirti: İlk girişte EULA ekranına düşüyorsunuz ve kabul düğmesi soluk kalıyor.

Olası sebep: düğme bir değil üç şart istiyor - sözleşmeyi sonuna kadar kaydırmak, okudum ve anladım kutusunu işaretlemek ve kabul ediyorum kutusunu işaretlemek.

Çözüm: sözleşme kutusunun kendisini sonuna kadar kaydırın. Sayfadan ayrı bir kaydırma alanıdır; sayfayı kaydırmak sayılmaz.

Panel, var olmayan bir alan adına yönlendiriyor

Belirti: Giriş başarılı oluyor ama tarayıcı açılamayan bir adrese iniyor.

Olası sebep: kurulumda girilen site adresi, gerçekte kullandığınız adres değil - bir yer tutucu alan adı ya da hâlâ http:// sunan bir sunucuda https://.

Çözüm: kök dizinindeki .env dosyasında SITE_URL değerini düzeltin ve yeniden giriş yapın. Eski oturum çerezi eski adrese aittir, taşınmaz.