Laravel 500 Hatası Çözümü ve Sık Karşılaşılan Laravel Hataları

Laravel sitenizde beyaz bir sayfanın ortasında yalnızca "500 | Server Error" yazıyorsa uygulama bir hatayla karşılaşmış, ama yayın ortamında olduğu için ayrıntıyı size göstermiyordur. Bu doğru davranıştır: hata ayrıntısı ziyaretçiye değil, günlük dosyasına yazılır. Bu rehberde Laravel 500 hatasının nedenini nasıl bulacağınızı, günlükte hiçbir şey yokken nereye bakmanız gerektiğini ve en sık karşılaşılan Laravel hatalarını (APP_KEY, izinler, Composer platform hatası, veritabanı, Vite manifest, 419 Page Expired, storage link) gerçek hata ekranlarıyla ve çözümleriyle anlatıyoruz.

Hata ekranları, bu yazı için kurulan gerçek bir Laravel 13.39 projesinde hatalar bilerek oluşturularak alınmıştır. Dosya yolları kısaltılmıştır.

---

500 Server Error Ne Anlama Gelir?

Bu sayfa, .env dosyasında APP_DEBUG=false iken Laravel'in gösterdiği genel hata sayfasıdır. Sayfada neden yazmaz; neden storage/logs klasöründeki günlük dosyasındadır. Yani ilk iş her zaman günlüğe bakmaktır, hata ayıklama modunu açmak değil.

---

Adım 1: Laravel Günlüğünü Okuyun

Günlük dosyası, varsayılan ayarda storage/logs/laravel.log, LOG_CHANNEL=daily kullanıyorsanız storage/logs/laravel-2026-10-31.log gibi tarihli bir dosyadır.

VDS'te:

cd /var/www/ornek
tail -n 50 storage/logs/laravel.log

cPanel'de: Dosya Yöneticisi'nde laravel/storage/logs klasörüne girin, en son değişen dosyayı seçip Görüntüle ile açın ve dosyanın en altına inin.

Her hata kaydı [tarih] ortam.SEVİYE: mesaj biçiminde başlar. İlk satır çoğu zaman yeterlidir: hatanın türünü (QueryException, MissingAppKeyException…), açıklamasını ve hangi dosyanın hangi satırında oluştuğunu söyler. Altındaki uzun liste (stack trace) hatanın oraya hangi yoldan geldiğini gösterir; kendi kodunuzdaki (app/, routes/) ilk satıra odaklanın.

---

Adım 2: Günlükte Hiçbir Şey Yoksa

"Laravel 500 error no log" durumunda iki olasılık vardır:

1. Laravel günlüğe yazamıyordur. storage klasörüne yazma izni yoksa Laravel hem asıl hatayı hem de günlüğü kaydedemez. Aşağıdaki "Permission denied" bölümüne bakın.
2. Hata Laravel başlamadan önce oluşuyordur. vendor klasörü eksikse, PHP sürümü uyumsuzsa ya da index.php'deki yollar yanlışsa Laravel hiç çalışmaz, dolayısıyla günlük de yazmaz. Bu hatalar web sunucusunun ve PHP'nin günlüğüne düşer:
   • VDS (Nginx): sudo tail -n 50 /var/log/nginx/error.log ve sudo journalctl -u php8.3-fpm -n 50
   • cPanel: Metrik bölümündeki Hatalar aracı, sitenizin web sunucusu hata günlüğünün son kayıtlarını gösterir. Ayrıca public_html içinde error_log adlı bir dosya oluşmuş olabilir.

---

Hata Ayıklama Modu: Yalnızca Kendi Bilgisayarınızda

APP_DEBUG=true olduğunda Laravel hatanın ayrıntılı sayfasını tarayıcıda gösterir:

Bu sayfa geliştirme için çok değerlidir, ama yayındaki bir sitede açık bırakılırsa veritabanı adı, sunucu dosya yolları, SQL sorguları ve istek bilgileri herkese görünür. Laravel'in kendi belgeleri de yayında bu değerin her zaman false olması gerektiğini söyler. Canlı sitede hata ayıklamanız gerekiyorsa günlüğü okuyun; çok gerekiyorsa birkaç dakikalığına açıp hemen kapatın ve php artisan optimize kullanıyorsanız ayarı yeniden önbelleğe alın.

---

En Sık Laravel Hataları ve Çözümleri

1. No application encryption key has been specified

Neden: .env dosyasında APP_KEY boştur ya da Laravel .env dosyasını bulamıyordur (dosya yanlış klasörde veya adı .env.txt olmuş).

Çözüm:

php artisan key:generate

SSH olmayan hostingte anahtarı kendi bilgisayarınızda php artisan key:generate --show ile üretip .env'e yapıştırın. Yayındaki bir sitenin anahtarını değiştirmeyin: tüm oturumlar düşer, encrypt() ile şifrelenmiş veriler okunamaz. Anahtarı değiştirmek zorundaysanız eski anahtarı APP_PREVIOUS_KEYS değişkenine yazın; Laravel eski anahtarla şifrelenmiş verileri çözmeye devam eder.

2. Permission denied: storage veya bootstrap/cache yazılamıyor

Günlükte ya da ekranda şu ifade görünür:

The stream or file "/var/www/ornek/storage/logs/laravel.log" could not be opened
in append mode: Failed to open stream: Permission denied

Neden: PHP'nin çalıştığı kullanıcı (www-data) storage veya bootstrap/cache klasörüne yazamıyordur. En sık senaryo: bir Artisan komutu root veya başka bir kullanıcıyla çalıştırılmış, laravel.log o kullanıcıya ait oluşturulmuştur.

Çözüm (VDS):

cd /var/www/ornek
sudo chown -R deploy:www-data storage bootstrap/cache
sudo chmod -R ug+rwX storage bootstrap/cache

Bundan sonra Artisan komutlarını sudo -u www-data php artisan ... biçiminde çalıştırın. 777 vermeyin; sorunu gizler ve sunucudaki her sürece yazma yetkisi verir.

cPanel hostingte PHP sizin kullanıcınızla çalıştığı için bu hata nadirdir; görülürse Dosya Yöneticisi'nde storage ve bootstrap/cache klasörlerinin iznini 755 yapın.

3. Composer detected issues in your platform

Composer detected issues in your platform:
Your Composer dependencies require a PHP version ">= 8.4.1".

Neden: vendor klasörünü hazırladığınız PHP sürümü, sitede çalışan sürümden yeni. Composer, bileşenleri çalıştığı PHP'ye göre seçer. Testimizde PHP 8.4 ile kurulan bir Laravel 13 projesi, PHP 8.4.1 isteyen bileşen sürümleriyle kilitlendi ve PHP 8.3 seçili ortamda yalnızca bu yazıyla açıldı. Laravel bu noktada henüz başlamadığı için laravel.log'a hiçbir şey yazılmaz.

Çözüm: İki yoldan biri:

• Sitede projeyi hazırladığınız PHP sürümünü seçin (cPanel'de MultiPHP Yöneticisi).
• Ya da projeye hedef sürümü söyleyip bağımlılıkları yeniden çözün:

composer config platform.php 8.3.0
composer update

Testimizde bu iki komut Symfony bileşenlerini 8.1'den PHP 8.3 ile uyumlu 7.4 sürümüne indirdi.

4. SQLSTATE: veritabanı bağlantı hataları

.env'i değiştirdikten sonra değişiklik yansımıyorsa ayarlar önbellektedir: php artisan optimize:clear ve ardından php artisan optimize çalıştırın.

5. Vite manifest not found

Neden: Sayfa şablonunda @vite(...) var ama CSS ve JavaScript dosyaları derlenmemiş ya da public/build klasörü sunucuya yüklenmemiş.

Çözüm: npm ci ve npm run build çalıştırın; paylaşımlı hostingte oluşan public/build klasörünü public_html/build olarak yükleyin. Geliştirmede npm run dev açık olmalıdır.

6. 419 Page Expired

Neden: Form gönderildiğinde Laravel isteğin sitenin kendisinden geldiğini doğrulayamamıştır (CSRF koruması). Laravel 13, tarayıcının gönderdiği Sec-Fetch-Site başlığına bakar; istek aynı kaynaktan geliyorsa token aramadan kabul eder. Başlık yoksa ya da istek başka bir adresten geliyorsa formdaki _token alanının oturumdaki değerle eşleşmesi gerekir. Testimizde aynı form, aynı siteden gönderildiğinde kabul edildi, farklı bir porttan (başka bir kaynaktan) gönderildiğinde 419 verdi.

Sık nedenler ve çözümler:

• Formda @csrf satırı yoktur. Her POST formuna ekleyin.
• Sayfa uzun süre açık kalmış, oturum süresi (SESSION_LIFETIME, varsayılan 120 dakika) dolmuştur.
• Oturum yazılamıyordur: SESSION_DRIVER=database iken sessions tablosu yoktur ya da storage/framework/sessions yazılamıyordur.
• Site HTTPS'e geçmiş ama APP_URL veya SESSION_DOMAIN eski adreste kalmıştır; çerez tarayıcıya ulaşmıyordur.
• Ödeme kuruluşu gibi dış bir sistemin geri çağrı (callback) adresidir. Bu adresleri bootstrap/app.php içinde $middleware->preventRequestForgery(except: ['odeme/geri-donus']) ile CSRF dışında bırakın ve isteği o sistemin imzasıyla doğrulayın.

7. storage link: görseller 404 veya "link already exists"

Yüklenen görseller açılmıyorsa public/storage bağlantısı yoktur. VDS'te php artisan storage:link çalıştırın. Komut şu hatayı veriyorsa:

ERROR  The [/var/www/ornek/public/storage] link already exists.

public/storage adında bağlantı değil gerçek bir klasör vardır (çoğunlukla FTP ile yükleme sırasında oluşur). İçinde dosya yoksa klasörü silip komutu yeniden çalıştırın; dosya varsa önce storage/app/public içine taşıyın.

Paylaşımlı hostingte symlink ve exec kapalı olduğundan storage:link "Call to undefined function Illuminate\Filesystem\exec()" hatası verir. Bu durumda bağlantı yerine dosyaları doğrudan public_html/storage içine yazan ayarı kullanın; adımları Laravel cPanel kurulumu rehberimizde anlattık.

8. Class "App..." not found

Neden: Yeni sınıf eklendikten sonra Composer'ın sınıf haritası güncellenmemiştir ya da dosya adı ile sınıf adının büyük küçük harfi farklıdır. Windows ve macOS dosya adlarında büyük küçük harfi ayırt etmez, Linux sunucular eder: app/Models/urun.php dosyasındaki Urun sınıfı bilgisayarınızda çalışır, sunucuda bulunamaz.

Çözüm: Dosya adını sınıf adıyla birebir aynı yapın ve composer dump-autoload -o çalıştırın (hostingte bunu yerelde yapıp vendor/composer klasörünü yükleyin).

9. Yerelden yüklenen önbellek dosyaları

Neden: Bilgisayarınızda php artisan optimize çalıştırıp bootstrap/cache klasörünü sunucuya yüklediyseniz, config.php dosyası bilgisayarınızdaki dosya yollarını ve yerel .env değerlerini içerir. Site yanlış veritabanına bağlanmaya çalışır ya da "No such file or directory" hatası verir.

Çözüm: Sunucudaki bootstrap/cache içindeki config.php, routes-v7.php, events.php ve services.php dosyalarını silin (packages.php kalabilir), ardından sunucuda php artisan optimize çalıştırın. Yükleme paketine bu dosyaları koymayın.

10. Ana sayfa açılıyor, diğer sayfalar 404

Neden: İstekler index.php'ye yönlendirilmiyordur.

• cPanel / LiteSpeed / Apache: public_html/.htaccess dosyası eksiktir. Gizli dosyaları gösterip Laravel'in public/.htaccess dosyasını yükleyin.
• Nginx: Sunucu bloğunda try_files $uri $uri/ /index.php?$query_string; satırı yoktur.

---

Hızlı Kontrol Listesi

---

Özet

1. "500 Server Error" gördüğünüzde hata ayıklama modunu açmayın; önce storage/logs içindeki son kayda bakın.
2. Günlük boşsa sorun Laravel başlamadan önce oluşuyordur: web sunucusu günlüğüne, vendor klasörüne, PHP sürümüne ve storage izinlerine bakın.
3. Yayında APP_DEBUG=false, APP_ENV=production olsun; APP_KEY'i yayındaki sitede değiştirmeyin.
4. vendor klasörünü sitede çalışan PHP sürümüyle hazırlayın ya da composer config platform.php kullanın.
5. İzin hatalarını 777 ile değil, doğru sahiplik ve yalnızca storage ile bootstrap/cache için yazma izniyle çözün.

Laravel kurulumunu baştan doğru yapmak bu hataların çoğunu önler: Laravel nedir ve nasıl kurulur, Laravel cPanel kurulumu ve Laravel VDS kurulumu rehberlerimize göz atın. AnkSOFT web hosting müşterileri sitelerinde PHP 8.3, 8.4 ve 8.5 arasında seçim yapabilir; kendi sunucusunu yönetmek isteyenler için VDS sunucu paketlerimiz uygundur. Hatayı çözemezseniz günlükteki ilk satırı ve hata ekranının görüntüsünü ekleyerek destek talebi açabilirsiniz; hosting altyapısından kaynaklanan sorunları inceleriz, uygulama kodunuzdaki hataların düzeltilmesi ise destek kapsamı dışındadır.

---

Kaynaklar

• Laravel Errors & Logging: hata yönetimi ve debug modu
• Laravel Logging: günlük kanalları, single ve daily
• Laravel Deployment: Debug Mode ve Directory Permissions
• Laravel Encryption: Gracefully Rotating Encryption Keys: APP_PREVIOUS_KEYS
• Laravel CSRF Protection: 419 hatası, @csrf ve hariç tutulan adresler
• Laravel Vite: npm run build ve manifest dosyası
• Composer: config.platform