Laravel 500 Hatası: 10 Kesin Çözüm

Laravel ile geliştirdiğiniz bir web sitesinde 500 Internal Server Error hatasıyla karşılaşmak, uygulamanın tamamen bozulduğu anlamına gelmez. Çoğu zaman hatanın kaynağı; .env yapılandırması, veritabanı bağlantısı, dosya izinleri, Composer bağımlılıkları, cache, PHP sürümü veya Laravel'in storage dizinindeki yazma problemleri gibi belirli bir noktada bulunabilir.

Özellikle Laravel uygulamaları cPanel veya başka bir production sunucusuna taşındığında 500 hatasıyla daha sık karşılaşılabilir.

Bu rehberde Laravel 500 hatasının nedenlerini adım adım tespit etmeyi ve çözmeyi anlatıyoruz.

Kısa cevap: Laravel 500 hatasında ilk yapmanız gereken şey rastgele dosya değiştirmek değil, storage/logs/laravel.log dosyasını kontrol etmektir.

---

Laravel 500 Hatası Nedir?

HTTP 500 Internal Server Error, sunucunun gelen isteği işlerken beklenmeyen bir hata ile karşılaştığını gösteren genel bir HTTP durum kodudur.

Laravel tarafında bu hata;

• PHP hatası,

• Laravel exception,

• veritabanı bağlantı problemi,

• yanlış .env ayarı,

• eksik Composer paketi,

• dosya izin problemi,

• cache problemi,

• yanlış PHP sürümü,

• hatalı sunucu yapılandırması

gibi birçok farklı nedenden kaynaklanabilir.

Bu nedenle ekranda yalnızca:

500 Internal Server Error

görmeniz, hatanın gerçek nedenini tek başına göstermez.

Laravel'in kendi log sistemi bu noktada en önemli teşhis kaynaklarından biridir. Laravel'in storage dizini uygulama loglarını, cache'leri ve framework tarafından oluşturulan çeşitli dosyaları barındırır.

---

Laravel 500 Hatası Neden Olur?

En sık karşılaşılan nedenleri şöyle sıralayabiliriz:

1. .env dosyasında yanlış yapılandırma

2. APP_KEY eksikliği

3. Veritabanı bağlantı hatası

4. storage veya bootstrap/cache izin problemi

5. Eksik vendor klasörü

6. Composer bağımlılıklarının bozulması

7. Laravel cache dosyalarının bozulması

8. PHP sürümünün Laravel ile uyumsuz olması

9. Hatalı kod veya exception

10. Web sunucusu yapılandırma problemi

Şimdi bunları tek tek inceleyelim.

---

1. Önce Laravel Loglarını Kontrol Edin

Laravel 500 hatasında yapılabilecek en büyük hata, doğrudan dosyaları değiştirmeye başlamaktır.

Önce hatanın ne olduğunu öğrenin.

Laravel uygulamanızın:

storage/logs/

klasörünü açın.

Burada genellikle:

laravel.log

dosyasını göreceksiniz.

cPanel Terminal kullanıyorsanız:

tail -n 100 storage/logs/laravel.log

komutuyla son 100 log satırını görüntüleyebilirsiniz.

Canlı olarak logları takip etmek için:

tail -f storage/logs/laravel.log

kullanabilirsiniz.

Örneğin log içerisinde:

SQLSTATE

görüyorsanız veritabanı tarafını,

Permission denied

görüyorsanız dosya izinlerini,

Class not found

görüyorsanız Composer veya namespace problemlerini,

APP_KEY

görüyorsanız .env yapılandırmasını incelemeniz gerekir.

Laravel topluluğundaki gerçek bir 500 hata örneğinde de sorunun kaynağını belirlemek için storage/logs ve web sunucusu loglarının kontrol edilmesi öneriliyor.

---

2. APP_DEBUG ile Gerçek Hatanın Görülmesini Sağlayın

Geliştirme ortamında Laravel'in hata detaylarını görmek için .env içerisindeki:

APP_DEBUG=true

ayarını kullanabilirsiniz.

Örneğin:

APP_ENV=local
APP_DEBUG=true

Bundan sonra sayfayı yenilediğinizde Laravel, genel 500 sayfası yerine hatanın ayrıntılarını gösterebilir.

Ancak burada çok önemli bir nokta var:

Production ortamında APP_DEBUG=true bırakmayın.

Laravel'in resmi dokümantasyonuna göre production ortamında APP_DEBUG değerinin false olması gerekir. true bırakılması, uygulamanın hassas yapılandırma bilgilerinin ziyaretçilere açığa çıkmasına neden olabilir.

Production için:

APP_DEBUG=false

kullanılmalıdır.

---

3. APP_KEY Eksikse 500 Hatası Oluşabilir

Laravel uygulamalarında .env dosyasındaki:

APP_KEY=

değeri önemli bir yapılandırmadır.

Yeni bir Laravel projesinde gerekli anahtar genellikle kurulum sırasında oluşturulur.

Eksikse:

php artisan key:generate

komutu kullanılabilir.

Laravel dokümantasyonunda da APP_KEY değerinin .env üzerinden kullanıldığı ve güvenli bir anahtar oluşturmak için php artisan key:generate komutunun önerildiği belirtiliyor.

Fakat dikkat:

Çalışan production sisteminde mevcut APP_KEY değerini gelişigüzel değiştirmeyin.

Çünkü Laravel'in encryption sistemi bu anahtarı kullanır ve anahtar değiştirildiğinde mevcut şifrelenmiş verilerin çözülmesi etkilenebilir; kullanıcı oturumları da sonlandırılabilir.

---

4. Veritabanı Bağlantısını Kontrol Edin

500 hatasının en yaygın nedenlerinden biri veritabanı bağlantısındaki problemdir.

.env dosyanızdaki değerleri kontrol edin:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=veritabani_adi
DB_USERNAME=kullanici_adi
DB_PASSWORD=sifre

cPanel kullanıyorsanız özellikle şu üç bilginin doğru olduğundan emin olun:

Database Name
Database Username
Database Password

Ayrıca cPanel'de oluşturulan MySQL kullanıcısının ilgili veritabanına atanmış olması gerekir.

Terminal üzerinden migration durumunu kontrol etmek için:

php artisan migrate:status

kullanabilirsiniz.

Burada bir SQLSTATE hatası görürseniz problem büyük ihtimalle Laravel'in genel 500 hatasından ziyade veritabanı bağlantısı veya sorgu tarafındadır.

---

5. storage ve bootstrap/cache İzinlerini Kontrol Edin

Laravel'in yazma işlemleri için bazı klasörlere erişebilmesi gerekir.

Özellikle:

storage/
bootstrap/cache/

dizinlerini kontrol edin.

Laravel'in storage klasörü loglar, cache, derlenmiş Blade dosyaları ve framework tarafından oluşturulan diğer dosyalar için kullanılır.

Linux/cPanel sunucusunda izinleri kontrol etmek için:

ls -ld storage
ls -ld bootstrap/cache

kullanabilirsiniz.

İzin problemi görüyorsanız hosting ortamınıza uygun izinleri uygulayın.

Örneğin bazı Linux sunucularında:

chmod -R 775 storage bootstrap/cache

kullanılabilir.

Ancak tüm sunucular için körü körüne aynı izinleri uygulamak doğru değildir. Dosya sahibi ve web sunucusunun hangi kullanıcıyla çalıştığı da dikkate alınmalıdır.

---

6. vendor Klasörü Eksikse Laravel Çalışmayabilir

Laravel'in Composer bağımlılıkları:

vendor/

klasöründe bulunur.

Sunucuya dosyaları FTP ile yüklediğinizde veya deployment sırasında vendor klasörünü göndermediğinizde Laravel uygulaması çalışmayabilir.

Örneğin:

vendor/autoload.php

eksikse uygulamanın bootstrap süreci başarısız olabilir.

Composer erişiminiz varsa:

composer install --no-dev --optimize-autoloader

çalıştırabilirsiniz.

Geliştirme ortamında ise:

composer install

kullanılabilir.

Laravel'in resmi kurulum dokümantasyonunda Composer'ın Laravel bağımlılıklarının kurulumu için temel araçlardan biri olduğu belirtilmektedir.

---

7. Laravel Cache Temizleme

Yanlış veya eski cache dosyaları da sorunların teşhisini zorlaştırabilir.

Laravel uygulamasının kök dizininde:

php artisan optimize:clear

komutunu çalıştırabilirsiniz.

Bu komut sonrasında uygulamanızı tekrar test edin.

Ayrıca ihtiyaca göre:

php artisan config:clear

ve:

php artisan cache:clear

gibi komutlar da kullanılabilir.

Özellikle .env üzerinde değişiklik yaptıktan sonra eski configuration cache'in devrede olması kafa karıştırabilir.

---

8. PHP Sürümünü Kontrol Edin

Laravel sürümü ile sunucudaki PHP sürümünün uyumlu olması gerekir.

Örneğin Laravel 12 için resmi sürüm dokümantasyonunda PHP 8.2–8.5 aralığı desteklenen sürümler arasında listelenmektedir.

Sunucudaki PHP sürümünü:

php -v

komutuyla kontrol edebilirsiniz.

cPanel kullanıyorsanız:

MultiPHP Manager

veya hosting sağlayıcınızın sunduğu PHP sürüm yönetim ekranından da kontrol edebilirsiniz.

Örneğin proje Laravel 12 kullanıyor ancak sunucu yanlış veya uyumsuz bir PHP sürümüyle çalışıyorsa uygulama beklenmedik hatalar verebilir.

---

9. Hatalı Kod veya Paketleri Kontrol Edin

Bazen sunucu tamamen doğru yapılandırılmıştır ancak uygulamanın kendisinde hata vardır.

Örneğin:

Call to undefined method

veya:

Class "App\Models\Example" not found

gibi bir hata görüyorsanız problem doğrudan kod veya Composer autoload yapısıyla ilgili olabilir.

Composer autoload dosyalarını yenilemek için:

composer dump-autoload

kullanabilirsiniz.

Ardından:

php artisan optimize:clear

çalıştırıp tekrar test edebilirsiniz.

---

10. Laravel'in public Dizini ve Sunucu Yapılandırmasını Kontrol Edin

Laravel uygulaması production ortamında doğru web root üzerinden servis edilmelidir.

Laravel dokümantasyonu, uygulamanın web sunucusunun document root'u olarak Laravel'in public dizininin kullanılmasını ve uygulamanın doğrudan web dizininin kökünden servis edilmemesini önerir. Bunun amacı uygulamanın hassas dosyalarının web üzerinden erişilebilir hale gelmesini önlemektir.

Doğru yapı kabaca:

proje/
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
│   ├── index.php
│   └── ...
├── resources/
├── routes/
├── storage/
├── vendor/
└── .env

şeklindedir.

Web sunucusunun document root'u mümkün olduğunca:

proje/public

olmalıdır.

cPanel hostinglerde ise hosting sağlayıcısının yapılandırmasına göre farklı deployment yöntemleri gerekebilir.

---

cPanel'de Laravel 500 Hatası İçin Hızlı Kontrol

cPanel Terminal erişiminiz varsa önce proje dizinine girin:

cd /home/kullanici/proje

Ardından:

php -v

php artisan --version

php artisan optimize:clear

ls -la

ve:

tail -n 100 storage/logs/laravel.log

komutlarını çalıştırabilirsiniz.

Sonrasında:

composer dump-autoload

ve gerekiyorsa:

composer install --no-dev --optimize-autoloader

çalıştırılabilir.

Ancak Composer kurulumunu production sisteminde mevcut composer.lock dosyasını dikkate almadan rastgele güncellemekten kaçının.

---

Laravel 500 Hatasında Hızlı Teşhis Tablosu

Logda gördüğünüz hata	Muhtemel neden
APP_KEY	.env / APP_KEY
SQLSTATE	Veritabanı
Permission denied	Dosya izinleri
Class not found	Composer / namespace
Vite manifest not found	Frontend build
Call to undefined method	Kod / paket uyumsuzluğu
Connection refused	Servis / veritabanı bağlantısı
Maximum execution time	PHP işlem süresi
Allowed memory size exhausted	PHP memory limit
No application encryption key	APP_KEY

Buradaki tabloyu kullanarak 500 hatasını tahmin etmek yerine logdaki gerçek exception üzerinden teşhis etmek çok daha sağlıklıdır.

---

Laravel 500 Hatası İçin En Hızlı Çözüm Sırası

Bir Laravel projesi çalışmıyorsa aşağıdaki sırayı uygulayın:

1. Logu açın

tail -n 100 storage/logs/laravel.log

2. PHP sürümünü kontrol edin

php -v

3. Laravel sürümünü kontrol edin

php artisan --version

4. Cache temizleyin

php artisan optimize:clear

5. Composer autoload yenileyin

composer dump-autoload

6. .env dosyasını kontrol edin

Özellikle:

APP_KEY
APP_ENV
APP_DEBUG
DB_*

alanlarını kontrol edin.

7. İzinleri kontrol edin

storage/
bootstrap/cache/

8. Veritabanını kontrol edin

php artisan migrate:status

9. vendor klasörünü kontrol edin

vendor/autoload.php

mevcut mu kontrol edin.

10. Sunucu loglarını kontrol edin

Laravel logunda bilgi yoksa PHP-FPM, Apache veya Nginx loglarına bakın.

---

Laravel 500 Hatasında APP_DEBUG Açmak Güvenli mi?

Geliştirme ortamında:

APP_DEBUG=true

faydalıdır.

Ancak canlı sitede:

APP_DEBUG=false

kullanılmalıdır.

Çünkü debug ekranı uygulamanın dosya yolları, yapılandırma bilgileri ve bazı durumlarda hassas veriler hakkında bilgi verebilir.

Laravel'in resmi dokümantasyonu da production ortamında APP_DEBUG değerinin false olması gerektiğini açıkça belirtmektedir.

---

Sonuç

Laravel 500 hatası tek başına belirli bir problemi ifade etmez. Bu hata, uygulamanın isteği işlerken sunucu tarafında beklenmeyen bir problem yaşadığını gösterir.

Bu nedenle çözüm sürecinde:

Log → Environment → PHP → Database → Permissions → Composer → Cache → Code → Server

sırasını takip etmek en doğru yaklaşımdır.

Özellikle cPanel üzerinde çalışan Laravel projelerinde .env, storage, bootstrap/cache, vendor, PHP sürümü ve document root yapılandırması birlikte kontrol edilmelidir.

En önemli komutlardan biri ise şudur:

tail -n 100 storage/logs/laravel.log

Çünkü 500 hatasını çözmenin en kısa yolu, hatanın gerçek nedenini logdan bulmaktır.

Bir sonraki rehberimizde ise Laravel'in çok sık karşılaşılan başka bir problemi olan 419 Page Expired hatasını; CSRF, session, .env, cookie ve cPanel yapılandırması üzerinden ele alacağız.