Eko Sudarmaji

Laravel 500 Internal Server Error: Penyebab dan Cara Mengatasinya

Laravel 500 Internal Server Error: Apa Penyebabnya?

Laravel 500 Internal Server Error adalah error yang menunjukkan bahwa server mengalami masalah ketika memproses request aplikasi. Kode HTTP 500 sendiri belum menunjukkan penyebab spesifiknya.

Pada Laravel, penyebab sebenarnya biasanya dapat ditemukan di log aplikasi, konfigurasi environment, database, PHP, permission file, atau dependency.

Jika website tiba-tiba menampilkan:

500 Internal Server Error

jangan langsung mengubah kode aplikasi. Langkah pertama adalah mencari error sebenarnya di log Laravel.

Laravel menyediakan mekanisme exception handling dan logging untuk mencatat exception yang terjadi pada aplikasi. (Laravel)

Secara umum, penyebab Laravel 500 Internal Server Error adalah:

  1. Konfigurasi .env salah.
  2. APP_KEY belum tersedia.
  3. Database tidak dapat diakses.
  4. Permission storage atau bootstrap/cache bermasalah.
  5. Dependency Composer tidak lengkap.
  6. Versi PHP tidak kompatibel.
  7. Cache konfigurasi masih menggunakan nilai lama.
  8. Error pada kode PHP atau Blade.
  9. Extension PHP yang dibutuhkan belum terpasang.
  10. Service seperti Redis atau queue mengalami masalah.

Cara Mengatasi Laravel 500 Internal Server Error

1. Cek Log Laravel Terlebih Dahulu

Ini adalah langkah paling penting.

Masuk ke directory aplikasi Laravel:

cd /var/www/laravel-app

Kemudian lihat log terbaru:

tail -n 100 storage/logs/laravel.log

Untuk memantau log secara realtime:

tail -f storage/logs/laravel.log

Cari bagian seperti:

production.ERROR

atau exception seperti:

SQLSTATE
PDOException
Class not found
Permission denied
No application encryption key has been specified

Pesan tersebut biasanya jauh lebih berguna daripada halaman 500 Internal Server Error yang tampil di browser.

Laravel memang dirancang untuk melaporkan exception berdasarkan konfigurasi logging aplikasi. (Laravel)

2. Periksa APP_DEBUG

Jika Anda sedang melakukan debugging di environment development, Anda dapat mengaktifkan:

APP_DEBUG=true

Kemudian:

php artisan optimize:clear

Refresh halaman.

Laravel dapat menampilkan detail exception ketika debug aktif. Namun, jangan mengaktifkan APP_DEBUG=true pada production, karena detail error dapat mengekspos informasi sensitif kepada pengguna. Dokumentasi Laravel secara eksplisit merekomendasikan APP_DEBUG=false di production.

Untuk production:

APP_ENV=production
APP_DEBUG=false

Jika perlu mengetahui penyebab error di production, baca log server daripada menampilkan stack trace kepada pengunjung.

3. Pastikan APP_KEY Sudah Ada

Salah satu penyebab Laravel gagal menjalankan aplikasi adalah application key belum tersedia.

Periksa:

grep APP_KEY .env

Jika belum ada, jalankan:

php artisan key:generate

Kemudian:

php artisan optimize:clear

Jangan mengganti APP_KEY pada aplikasi production secara sembarangan. Perubahan key dapat berdampak pada data yang sebelumnya dienkripsi menggunakan key lama.

4. Periksa File .env

Kesalahan konfigurasi .env sangat sering menyebabkan HTTP 500 setelah deployment.

Periksa konfigurasi utama:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://domainanda.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=laravel_user
DB_PASSWORD=password_database

Jika menggunakan Redis:

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Pastikan setiap nilai sesuai dengan environment server.

Kesalahan kecil seperti database name, username, password, host, atau port dapat membuat Laravel gagal melakukan boot atau gagal menjalankan request.

5. Bersihkan Cache Laravel

Jika .env sudah diperbaiki tetapi error tetap muncul, konfigurasi lama mungkin masih tersimpan di cache.

Jalankan:

php artisan optimize:clear

Perintah tersebut berguna untuk membersihkan cache yang dibuat Laravel.

Setelah aplikasi sudah benar, konfigurasi production dapat di-cache kembali:

php artisan optimize

Laravel sendiri merekomendasikan optimize sebagai bagian dari proses deployment production.

Untuk kasus khusus konfigurasi:

php artisan config:clear

Kemudian jika sudah yakin konfigurasi benar:

php artisan config:cache

Perlu diperhatikan bahwa setelah konfigurasi di-cache, .env tidak lagi dibaca secara langsung untuk setiap request; pemanggilan env() seharusnya berada di file konfigurasi Laravel.

6. Cek Koneksi Database

Jika log menunjukkan:

SQLSTATE

atau:

SQLSTATE[HY000]

kemungkinan masalah berasal dari database.

Periksa .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=laravel_user
DB_PASSWORD=password_database

Pastikan MySQL aktif:

sudo systemctl status mysql

Kemudian coba koneksi:

mysql -u laravel_user -p laravel_app

Jika login gagal, masalahnya bukan pada route Laravel, tetapi pada konfigurasi atau akses database.

Setelah memperbaiki .env:

php artisan optimize:clear

Kemudian coba kembali aplikasi.

7. Periksa Permission storage dan bootstrap/cache

Laravel perlu dapat menulis file pada directory tertentu, terutama:

storage
bootstrap/cache

Pada Ubuntu dengan Nginx dan PHP-FPM, permission yang salah dapat menghasilkan error 500.

Periksa:

ls -la storage
ls -la bootstrap/cache

Atur ownership sesuai user yang digunakan server:

sudo chown -R deploy:www-data /var/www/laravel-app

Kemudian:

sudo chmod -R 775 storage
sudo chmod -R 775 bootstrap/cache

Jika menggunakan struktur user atau PHP-FPM yang berbeda, sesuaikan ownership dengan konfigurasi server.

Hindari solusi seperti:

chmod -R 777 .

Permission 777 bukan solusi ideal untuk production karena memberikan hak akses terlalu luas.

8. Jalankan composer install

Jika error muncul setelah upload atau deployment aplikasi, dependency Composer mungkin belum terpasang dengan benar.

Jalankan:

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

Kemudian:

php artisan optimize:clear

Jika muncul error seperti:

Class "..." not found

periksa apakah package tersebut memang tersedia di composer.json.

Jika repository sudah memiliki composer.lock, sebaiknya gunakan dependency yang dikunci oleh project daripada melakukan update package secara sembarangan.

9. Periksa Versi PHP

Laravel membutuhkan versi PHP yang sesuai dengan versi framework dan dependency aplikasi.

Periksa:

php -v

Contoh:

PHP 8.x.x

Kemudian periksa requirement project:

cat composer.json

Cari bagian:

"require": {
    "php": "..."
}

Jika aplikasi membutuhkan versi PHP tertentu tetapi VPS menggunakan versi berbeda, aplikasi dapat gagal berjalan atau dependency tidak dapat digunakan dengan benar.

Jika menggunakan PHP-FPM, jangan hanya memeriksa PHP CLI.

Periksa juga:

systemctl status php8.x-fpm

Ganti 8.x sesuai versi PHP yang terpasang.

10. Pastikan Extension PHP Lengkap

Laravel dan dependency aplikasi dapat membutuhkan extension PHP tertentu.

Periksa extension:

php -m

Beberapa extension yang umum digunakan:

mbstring
openssl
pdo
tokenizer
xml
ctype
json
curl
fileinfo

Jika menggunakan MySQL, pastikan tersedia:

pdo_mysql

Jika menggunakan Redis, pastikan driver yang diperlukan aplikasi juga tersedia.

Anda dapat mencari error extension yang hilang melalui log Laravel atau output Composer.

11. Periksa Error pada Blade

HTTP 500 juga dapat disebabkan oleh error pada Blade template.

Misalnya ada syntax yang salah:

{{ $user->name }}

ketika object atau property yang digunakan tidak tersedia sesuai konteks aplikasi.

Untuk mengetahui error sebenarnya, lihat:

tail -f storage/logs/laravel.log

Jika error terjadi setelah Anda baru saja mengubah file Blade, controller, model, atau service, fokuskan pemeriksaan pada perubahan terakhir tersebut.

12. Periksa Route dan Controller

Jika hanya satu halaman yang menghasilkan HTTP 500 sedangkan halaman lain normal, kemungkinan besar masalah berada pada kode route, controller, service, query, atau view yang digunakan halaman tersebut.

Periksa route:

php artisan route:list

Kemudian telusuri alurnya:

Request
   ↓
Route
   ↓
Controller
   ↓
Service / Model
   ↓
Database / Redis / API
   ↓
View

Jika semua halaman menghasilkan 500, fokuskan pemeriksaan pada konfigurasi aplikasi, bootstrap Laravel, PHP-FPM, permission, atau dependency.

13. Periksa Nginx Error Log

Jika Laravel tidak menghasilkan informasi yang cukup, periksa log Nginx:

sudo tail -f /var/log/nginx/error.log

Perhatikan pesan seperti:

connect() to unix:/run/php/php8.x-fpm.sock failed

atau:

Permission denied

atau:

FastCGI sent in stderr

Jika muncul masalah PHP-FPM, periksa:

sudo systemctl status php8.x-fpm

Kemudian restart jika memang diperlukan:

sudo systemctl restart php8.x-fpm

Pastikan nama service sesuai versi PHP pada server.

14. Periksa Konfigurasi Nginx Laravel

Untuk Laravel, document root Nginx harus menunjuk ke directory:

/var/www/laravel-app/public

Contoh:

server {
    listen 80;
    server_name domainanda.com;

    root /var/www/laravel-app/public;

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.x-fpm.sock;
    }
}

Kemudian tes konfigurasi:

sudo nginx -t

Jika valid:

sudo systemctl reload nginx

Kesalahan pada root, try_files, atau socket PHP-FPM dapat menyebabkan aplikasi tidak berjalan sebagaimana mestinya.

15. Jika Menggunakan Redis, Pastikan Redis Aktif

Jika log menunjukkan error seperti:

Connection refused

dan stack trace mengarah ke Redis, periksa service Redis:

sudo systemctl status redis

Tes:

redis-cli ping

Respons normal:

PONG

Kemudian periksa:

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Jika Laravel dan Redis berada di Docker container berbeda, 127.0.0.1 biasanya bukan hostname Redis. Gunakan nama service Redis yang sesuai konfigurasi Docker.

16. Jika Menggunakan Queue, Periksa Worker

Aplikasi dapat terlihat normal pada beberapa halaman tetapi gagal memproses fitur tertentu karena queue worker bermasalah.

Periksa konfigurasi:

QUEUE_CONNECTION=redis

atau:

QUEUE_CONNECTION=database

Kemudian jalankan worker untuk pengujian:

php artisan queue:work

Jika worker langsung menghasilkan exception, penyebabnya dapat ditemukan dari output tersebut.

Pada production, worker sebaiknya dijalankan menggunakan process manager atau mekanisme service yang dapat melakukan restart otomatis.

17. Jalankan Artisan untuk Memastikan Laravel Bisa Boot

Salah satu cara cepat mengetahui apakah masalah terjadi pada Laravel secara keseluruhan adalah menjalankan:

php artisan about

Jika command tersebut gagal dengan exception, kemungkinan masalah terjadi pada konfigurasi atau proses bootstrap Laravel.

Anda juga dapat menjalankan:

php artisan optimize:clear

Jika command Artisan saja gagal, jangan fokus dulu pada Nginx. Perbaiki error yang muncul dari Artisan.

18. Gunakan Health Check Laravel

Pada versi Laravel yang mendukung health routing, aplikasi dapat menyediakan endpoint health check seperti:

/up

Endpoint tersebut dapat mengembalikan HTTP 200 ketika aplikasi berhasil melakukan boot dan 500 ketika boot gagal. Laravel menyediakan health route ini untuk membantu monitoring aplikasi production.

Contohnya:

curl -I https://domainanda.com/up

Jika hasilnya:

HTTP/2 200

aplikasi berhasil melewati health check.

Jika:

HTTP/2 500

periksa log Laravel untuk mengetahui exception yang menyebabkan aplikasi gagal.

19. Jangan Langsung Menghapus Semua Cache

Ketika mendapatkan HTTP 500, banyak developer langsung menjalankan berbagai command secara acak.

Lebih aman menggunakan urutan:

php artisan optimize:clear
composer install --no-dev --optimize-autoloader
php artisan about

Kemudian periksa:

tail -n 100 storage/logs/laravel.log

Jika aplikasi sudah diperbaiki dan siap production:

php artisan optimize

Laravel menyediakan optimize:clear untuk menghapus cache optimasi dan optimize untuk membangun cache yang diperlukan pada deployment.

Penyebab Laravel 500 Berdasarkan Pesan Error

Pesan/ErrorKemungkinan PenyebabSolusi Awal
No application encryption keyAPP_KEY belum tersediaphp artisan key:generate
SQLSTATEDatabase bermasalahCek konfigurasi DB_*
Connection refusedService seperti Redis/MySQL tidak dapat diaksesCek service dan host/port
Class not foundDependency atau autoload bermasalahcomposer install
Permission deniedPermission file/directoriesPeriksa storage dan bootstrap/cache
Call to undefined functionExtension PHP belum tersediaInstall extension yang dibutuhkan
Allowed memory size exhaustedMemory PHP tidak mencukupiPeriksa memory usage dan konfigurasi PHP
Maximum execution time exceededProses terlalu lamaPeriksa query/proses dan konfigurasi PHP
502 Bad GatewayPHP-FPM bermasalahPeriksa PHP-FPM dan socket
Blank/500 setelah perubahan .envCache konfigurasiphp artisan optimize:clear

Checklist Cepat Mengatasi Laravel 500

Jika Anda ingin troubleshooting dengan urutan paling efektif, gunakan checklist berikut:

  • Buka storage/logs/laravel.log.
  • Cari exception terbaru.
  • Periksa .env.
  • Pastikan APP_KEY tersedia.
  • Pastikan APP_DEBUG=false di production.
  • Jalankan php artisan optimize:clear.
  • Periksa koneksi database.
  • Periksa Redis jika digunakan.
  • Jalankan composer install --no-dev --optimize-autoloader.
  • Periksa versi PHP.
  • Periksa extension PHP.
  • Periksa permission storage.
  • Periksa permission bootstrap/cache.
  • Periksa PHP-FPM.
  • Periksa Nginx error log.
  • Periksa perubahan kode terakhir.
  • Jalankan php artisan about.
  • Uji kembali aplikasi.

FAQ Laravel 500 Internal Server Error

Apa arti Laravel 500 Internal Server Error?

HTTP 500 berarti server mengalami kondisi yang membuat request tidak dapat diproses dengan normal. Kode 500 sendiri tidak menjelaskan penyebab spesifiknya, sehingga log Laravel atau server perlu diperiksa.

Kenapa Laravel tiba-tiba error 500 setelah deploy?

Penyebab yang umum adalah .env production belum benar, APP_KEY tidak tersedia, dependency belum di-install, permission salah, PHP tidak kompatibel, database tidak dapat diakses, atau konfigurasi Laravel masih menggunakan cache lama.

Bagaimana cara melihat penyebab error 500 Laravel?

Periksa log:

tail -f storage/logs/laravel.log

Jika masalah berkaitan dengan web server, periksa:

sudo tail -f /var/log/nginx/error.log

Apakah APP_DEBUG=true bisa memperbaiki error 500?

Tidak. APP_DEBUG=true hanya membuat detail error lebih terlihat ketika debugging. Pada production, Laravel merekomendasikan APP_DEBUG=false agar informasi sensitif tidak terekspos.

Apakah php artisan optimize:clear aman dijalankan?

Perintah tersebut memang disediakan Laravel untuk membersihkan cache optimasi. Ini sering berguna setelah perubahan .env atau konfigurasi, terutama ketika aplikasi masih menggunakan konfigurasi lama.

Kesimpulan

Laravel 500 Internal Server Error bukan satu jenis error tertentu. Kode tersebut hanya menunjukkan bahwa terjadi masalah ketika aplikasi memproses request.

Cara paling efektif untuk mengatasinya adalah jangan menebak penyebab dari halaman 500. Mulailah dari log:

tail -f storage/logs/laravel.log

Setelah mengetahui exception, periksa komponen yang relevan:

500 Error
   ↓
Laravel Log
   ↓
Exception
   ↓
.env / Database / PHP / Permission / Dependency
   ↓
Perbaikan
   ↓
php artisan optimize:clear
   ↓
Test ulang

Untuk deployment production, pastikan APP_DEBUG=false, konfigurasi .env benar, dependency sudah terpasang, permission sesuai, PHP-FPM dan database aktif, serta log dapat dipantau. Laravel juga menyediakan mekanisme optimasi dan health check yang dapat membantu menjaga aplikasi production tetap mudah dipantau.

Dengan pendekatan tersebut, error Laravel 500 Internal Server Error dapat ditangani berdasarkan penyebab sebenarnya, bukan sekadar mencoba berbagai command secara acak.

Artikel Terkait