Masgani.com

Cara Mengatasi Laravel Error 500 Setelah Deploy ke cPanel

Error 500 setelah deploy Laravel ke cPanel adalah salah satu masalah yang cukup sering muncul, terutama di shared hosting. Biasanya halaman hanya menampilkan pesan singkat seperti 500 Internal Server Error, tanpa penjelasan detail.

Masalahnya, error 500 di Laravel tidak selalu berasal dari satu penyebab. Bisa karena file .env salah, permission folder tidak sesuai, cache config masih menyimpan data lama, versi PHP tidak cocok, dependency Composer belum lengkap, atau path aplikasi belum benar.

Di artikel ini saya rangkum langkah troubleshooting yang biasa saya lakukan saat Laravel tiba-tiba error 500 setelah dipindahkan ke cPanel. Urutannya dibuat dari yang paling aman, supaya tidak langsung mengubah banyak hal di server production.

Gejala Laravel Error 500 Setelah Deploy ke cPanel

Beberapa gejala yang sering muncul:

  • Website hanya menampilkan halaman putih
  • Muncul pesan 500 Internal Server Error
  • Route Laravel tidak bisa dibuka
  • Halaman utama error, tapi file statis seperti gambar masih bisa diakses
  • Error hanya terjadi di hosting, sedangkan di lokal normal
  • Setelah git pull atau auto deploy, website langsung error
  • Error muncul setelah menjalankan composer install, npm run build, atau php artisan optimize

Pada cPanel, error 500 biasanya tidak langsung menampilkan detail karena mode production memang menyembunyikan error asli. Jadi langkah pertama bukan menebak, tetapi membaca log.

Langkah Pertama: Cek Log Laravel

Laravel biasanya menyimpan log error di folder berikut:

storage/logs/laravel.log

Jika punya akses SSH, masuk ke folder project Laravel lalu jalankan:

tail -n 100 storage/logs/laravel.log

Untuk melihat log secara realtime:

tail -f storage/logs/laravel.log

Cari error terakhir yang muncul. Biasanya di bagian bawah file log.

Contoh error yang sering ditemukan:

The stream or file "/home/user/project/storage/logs/laravel.log" could not be opened in append mode: Permission denied

Atau:

SQLSTATE[HY000] [1045] Access denied for user

Atau:

No application encryption key has been specified.

Dari log ini kita bisa tahu arah masalahnya. Jangan langsung menghapus file atau menjalankan command sembarangan sebelum tahu error utamanya.

Cek Juga Error Log dari cPanel

Selain log Laravel, cPanel juga punya error log sendiri. Biasanya bisa dicek melalui:

cPanel → Metrics → Errors

Atau jika lewat SSH, tergantung konfigurasi hosting, error bisa muncul di file seperti:

~/logs/error_log

atau:

public_html/error_log

Jika project Laravel diarahkan ke public_html, coba cek:

tail -n 100 public_html/error_log

Error log cPanel berguna untuk mendeteksi masalah seperti:

  • Permission file salah
  • File .htaccess bermasalah
  • PHP fatal error
  • Extension PHP belum aktif
  • Path index.php tidak sesuai

Penyebab Umum Laravel Error 500 di cPanel

Berikut penyebab yang paling sering saya temui.

1. File .env Belum Ada atau Isinya Salah

Laravel membutuhkan file .env untuk membaca konfigurasi aplikasi, database, cache, mail, dan APP_KEY.

Cek apakah file .env ada:

ls -la

Pastikan ada file:

.env

Jika belum ada, salin dari .env.example:

cp .env.example .env

Lalu edit isinya sesuai konfigurasi hosting.

Contoh konfigurasi penting:

APP_NAME="Nama Website"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://domainanda.com

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=username_database
DB_USERNAME=username_dbuser
DB_PASSWORD=password_database

Jika menggunakan PostgreSQL:

DB_CONNECTION=pgsql
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=nama_database
DB_USERNAME=nama_user
DB_PASSWORD=password_database

Kesalahan kecil seperti nama database salah, password salah, atau host database tidak sesuai bisa langsung menyebabkan error 500.

2. APP_KEY Belum Digenerate

Jika log menampilkan error seperti ini:

No application encryption key has been specified.

Artinya APP_KEY belum ada.

Jalankan:

php artisan key:generate

Jika di cPanel PHP default bukan versi yang sesuai, gunakan path PHP dari cPanel. Contoh:

/opt/alt/php82/usr/bin/php artisan key:generate

Atau untuk PHP 8.3:

/opt/alt/php83/usr/bin/php artisan key:generate

Setelah itu cek file .env, harus ada nilai seperti:

APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Jika aplikasi sudah production dan sebelumnya punya APP_KEY lama, jangan asal generate ulang. Mengganti APP_KEY bisa membuat data terenkripsi lama tidak bisa dibaca, misalnya session, token, atau data terenkripsi tertentu.

3. Permission Folder storage dan bootstrap/cache Salah

Laravel perlu menulis file ke folder storage dan bootstrap/cache.

Jika permission salah, biasanya muncul error seperti:

Permission denied

atau:

The stream or file storage/logs/laravel.log could not be opened

Jalankan:

chmod -R 775 storage bootstrap/cache

Jika masih error, coba:

chmod -R 755 storage bootstrap/cache

Pada beberapa shared hosting, permission yang terlalu terbuka seperti 777 justru bisa memicu error karena diblokir oleh server.

Jangan langsung menggunakan:

chmod -R 777 storage bootstrap/cache

Kecuali benar-benar paham risikonya dan hanya untuk testing sementara. Di shared hosting, permission 777 sering tidak disarankan.

4. Cache Config Laravel Masih Menyimpan Konfigurasi Lama

Ini sangat sering terjadi setelah deploy.

Misalnya .env sudah diperbaiki, tapi Laravel tetap membaca konfigurasi lama karena config cache masih aktif.

Jalankan:

php artisan optimize:clear

Jika perlu, lanjutkan:

php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear

Setelah konfigurasi sudah benar, baru cache ulang:

php artisan config:cache
php artisan route:cache
php artisan view:cache

Untuk deployment di cPanel, saya biasanya memasukkan ini ke workflow deploy:

php artisan optimize:clear
php artisan migrate --force
php artisan optimize

Namun untuk production, pastikan migration sudah dicek dulu sebelum dijalankan otomatis.

5. Dependency Composer Belum Terinstall

Jika folder vendor belum ada atau tidak lengkap, Laravel tidak akan bisa berjalan.

Cek:

ls -la vendor

Jika belum ada, jalankan:

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

Jika Composer di hosting menggunakan versi PHP yang salah, jalankan dengan PHP yang sesuai:

/opt/alt/php82/usr/bin/php /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader

Atau jika Composer tersedia langsung:

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

Setelah selesai, jalankan:

php artisan optimize:clear
php artisan optimize

6. Versi PHP Tidak Cocok dengan Laravel

Laravel versi baru membutuhkan versi PHP tertentu. Jika hosting masih menggunakan PHP lama, error 500 bisa terjadi.

Cek versi PHP via SSH:

php -v

Namun perlu diingat, versi PHP di terminal SSH belum tentu sama dengan versi PHP website di cPanel.

Cek juga melalui:

cPanel → MultiPHP Manager

Pastikan domain menggunakan versi PHP yang sesuai dengan project Laravel.

Contoh umum:

  • Laravel 10: minimal PHP 8.1
  • Laravel 11: minimal PHP 8.2
  • Laravel 12: cek requirement project dan composer.json

Cek juga file composer.json:

"require": {
    "php": "^8.2"
}

Jika project butuh PHP 8.2 tapi domain masih memakai PHP 8.0, website bisa error 500.

7. Extension PHP Belum Aktif

Beberapa package Laravel membutuhkan extension PHP tertentu.

Cek extension PHP:

php -m

Extension yang sering dibutuhkan Laravel:

bcmath
ctype
curl
dom
fileinfo
json
mbstring
openssl
pdo
tokenizer
xml
zip

Jika menggunakan MySQL, pastikan ada:

pdo_mysql

Jika menggunakan PostgreSQL, pastikan ada:

pdo_pgsql
pgsql

Di cPanel, extension biasanya bisa diaktifkan melalui:

cPanel → Select PHP Version → Extensions

atau:

cPanel → MultiPHP INI Editor

Tergantung konfigurasi hosting.

8. Document Root Tidak Mengarah ke Folder public

Laravel harus dijalankan dari folder public, bukan dari root project.

Struktur Laravel normal:

project-laravel/
├── app/
├── bootstrap/
├── config/
├── public/
│   └── index.php
├── resources/
├── routes/
├── storage/
├── vendor/
└── .env

Document root domain sebaiknya mengarah ke:

/home/user/project-laravel/public

Jika di cPanel tidak bisa mengubah document root domain utama, biasanya ada dua pendekatan:

  1. Deploy Laravel di luar public_html, lalu arahkan public_html ke folder public
  2. Pindahkan isi folder public Laravel ke public_html, lalu sesuaikan path di index.php

Contoh isi index.php jika file public dipindah ke public_html:

require __DIR__.'/../project-laravel/vendor/autoload.php';

$app = require_once __DIR__.'/../project-laravel/bootstrap/app.php';

Pastikan path tersebut sesuai dengan lokasi folder Laravel di hosting.

Kesalahan path di index.php sering menyebabkan error 500 atau blank page.

9. File .htaccess Hilang atau Salah

Laravel membutuhkan .htaccess di folder public.

Contoh .htaccess default Laravel:

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

Cek apakah file .htaccess ada:

ls -la public

Jika file tidak terlihat di File Manager cPanel, aktifkan opsi Show Hidden Files.

Tanpa .htaccess, route Laravel bisa error, redirect tidak jalan, atau halaman tertentu tidak bisa dibuka.

10. Database Belum Dimigrasi

Kadang halaman error 500 terjadi karena tabel database belum ada.

Contoh error di log:

SQLSTATE[42S02]: Base table or view not found

Jalankan migration:

php artisan migrate --force

Untuk production, gunakan --force karena Laravel akan meminta konfirmasi jika environment production.

Sebelum menjalankan migration di website aktif, sebaiknya backup database dulu.

Contoh backup MySQL:

mysqldump -u username_db -p nama_database > backup.sql

Setelah backup aman, baru jalankan:

php artisan migrate --force

11. Storage Link Belum Dibuat

Jika error terjadi saat membuka gambar, file upload, atau halaman yang mengambil file dari storage, kemungkinan storage:link belum dijalankan.

Jalankan:

php artisan storage:link

Jika gagal karena link sudah ada, hapus symlink lama dengan hati-hati:

rm public/storage
php artisan storage:link

Pastikan jangan menghapus folder storage utama:

storage/

Yang dihapus hanya symlink:

public/storage

12. File Hasil Build Frontend Belum Ada

Jika Laravel menggunakan Vite, pastikan asset sudah dibuild.

Biasanya folder hasil build ada di:

public/build

Jalankan:

npm install
npm run build

Namun di shared hosting, npm run build kadang gagal karena memory terbatas. Jika begitu, build lebih aman dilakukan di lokal atau GitHub Actions, lalu hasil public/build ikut dideploy ke hosting.

Contoh error build yang sering muncul di shared hosting:

JavaScript heap out of memory

atau:

WebAssembly.instantiate(): Out of memory

Solusi yang lebih aman:

npm run build

di lokal, lalu upload folder:

public/build

ke server.

Jika menggunakan Git, pastikan .gitignore tidak mengabaikan folder build jika memang ingin dideploy.

13. Mode Debug untuk Sementara Saat Troubleshooting

Di production, sebaiknya:

APP_DEBUG=false

Namun saat troubleshooting awal, jika log tidak membantu, boleh aktifkan sementara:

APP_DEBUG=true

Setelah itu jalankan:

php artisan optimize:clear

Reload website dan lihat error detailnya.

Setelah masalah ditemukan, segera kembalikan:

APP_DEBUG=false

Lalu jalankan lagi:

php artisan optimize:clear
php artisan optimize

Jangan membiarkan APP_DEBUG=true di website production karena bisa membocorkan path server, konfigurasi, dan detail error aplikasi.

Urutan Troubleshooting yang Saya Sarankan

Agar tidak bingung, gunakan urutan berikut:

tail -n 100 storage/logs/laravel.log

Lalu cek permission:

chmod -R 775 storage bootstrap/cache

Bersihkan cache:

php artisan optimize:clear

Cek APP_KEY:

php artisan key:generate

Jika APP_KEY sudah ada, jangan generate ulang sembarangan.

Cek dependency:

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

Cek migration:

php artisan migrate --force

Cek optimasi ulang:

php artisan optimize

Jika masih error, cek log cPanel:

tail -n 100 public_html/error_log

Contoh .cpanel.yml untuk Deploy Laravel

Jika menggunakan Git Version Control di cPanel, file .cpanel.yml bisa membantu menjalankan command otomatis setelah push.

Contoh sederhana:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/username/project-laravel
    - cd $DEPLOYPATH
    - composer install --no-dev --optimize-autoloader
    - php artisan optimize:clear
    - php artisan migrate --force
    - php artisan storage:link
    - php artisan optimize

Jika PHP CLI default tidak sesuai, gunakan path PHP dari cPanel:

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/username/project-laravel
    - cd $DEPLOYPATH
    - /opt/alt/php82/usr/bin/php /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader
    - /opt/alt/php82/usr/bin/php artisan optimize:clear
    - /opt/alt/php82/usr/bin/php artisan migrate --force
    - /opt/alt/php82/usr/bin/php artisan storage:link
    - /opt/alt/php82/usr/bin/php artisan optimize

Sesuaikan:

/home/username/project-laravel

dengan path project Laravel Anda.

Jangan langsung copy-paste ke production tanpa menyesuaikan versi PHP, path Composer, dan lokasi project.

Cara Memastikan Masalah Sudah Selesai

  • [ ] Website tidak lagi menampilkan error 500
  • [ ] File storage/logs/laravel.log tidak menampilkan error baru setelah reload halaman
  • [ ] Error log cPanel tidak menampilkan PHP fatal error
  • [ ] File .env sudah sesuai dengan database hosting
  • [ ] APP_KEY sudah ada dan tidak kosong
  • [ ] Folder storage dan bootstrap/cache bisa ditulis Laravel
  • [ ] Versi PHP domain sesuai dengan requirement Laravel
  • [ ] Dependency Composer sudah lengkap
  • [ ] Migration database sudah dijalankan jika dibutuhkan
  • [ ] Folder public/build tersedia jika menggunakan Vite
  • [ ] APP_DEBUG sudah dikembalikan ke false

Kesalahan yang Perlu Dihindari

  • Mengaktifkan APP_DEBUG=true terlalu lama di production
  • Menjalankan php artisan key:generate ulang pada aplikasi production tanpa memahami risikonya
  • Menggunakan permission 777 secara permanen
  • Menghapus folder storage karena salah mengira itu cache
  • Lupa menjalankan php artisan optimize:clear setelah mengubah .env
  • Mengarahkan domain ke root Laravel, bukan ke folder public
  • Menjalankan migration production tanpa backup database
  • Menganggap error 500 selalu karena .htaccess
  • Menggunakan versi PHP CLI yang berbeda dengan versi PHP domain
  • Build asset langsung di shared hosting yang memorinya terbatas tanpa fallback

FAQ

Kenapa Laravel error 500 setelah deploy ke cPanel?

Penyebab paling umum adalah konfigurasi .env salah, APP_KEY belum ada, permission folder storage bermasalah, cache config masih menyimpan data lama, dependency Composer belum terinstall, atau versi PHP hosting tidak sesuai.

Bagaimana cara melihat penyebab asli error 500 Laravel?

Cek file log Laravel di:

storage/logs/laravel.log

Gunakan command:

tail -n 100 storage/logs/laravel.log

Jika tidak ada informasi, cek error log dari cPanel melalui menu Metrics → Errors atau file error_log.

Apakah aman mengaktifkan APP_DEBUG di hosting?

Aman hanya untuk sementara saat troubleshooting. Setelah error ditemukan, segera ubah kembali:

APP_DEBUG=false

Lalu jalankan:

php artisan optimize:clear

Jangan membiarkan debug aktif di production.

Apakah harus menjalankan composer install di cPanel?

Ya, jika folder vendor belum ikut terupload atau dependency berubah. Command yang umum digunakan:

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

Jika hosting tidak kuat menjalankan Composer, bisa install dependency di lokal lalu upload folder vendor, meskipun untuk workflow jangka panjang lebih rapi menggunakan deploy otomatis.

Kenapa setelah mengubah .env, Laravel tetap error?

Kemungkinan Laravel masih membaca config cache lama. Jalankan:

php artisan optimize:clear

Setelah konfigurasi benar, cache ulang dengan:

php artisan optimize

Apakah Laravel harus diarahkan ke folder public?

Ya. Document root Laravel sebaiknya mengarah ke folder:

public

Jika domain diarahkan ke root project Laravel, struktur aplikasi bisa bermasalah dan juga berisiko mengekspos file sensitif seperti .env.

Kenapa error 500 hanya muncul di cPanel, tapi di lokal normal?

Biasanya karena environment berbeda. Misalnya versi PHP berbeda, extension PHP belum aktif, permission folder berbeda, database hosting berbeda, atau file hasil build frontend belum tersedia di server.

Kesimpulan

Laravel error 500 setelah deploy ke cPanel hampir selalu bisa dilacak dari log. Jangan langsung menebak atau mengubah banyak konfigurasi sekaligus.

Urutan paling aman adalah cek storage/logs/laravel.log, cek error log cPanel, pastikan .env benar, cek APP_KEY, perbaiki permission storage dan bootstrap/cache, jalankan optimize:clear, pastikan Composer dependency lengkap, lalu cek versi PHP dan extension yang dibutuhkan.

Jika menggunakan shared hosting, hati-hati dengan proses build frontend dan Composer karena resource server sering terbatas. Untuk production, biasakan backup database sebelum migration dan jangan membiarkan APP_DEBUG=true aktif terlalu lama.

Rekomendasi Artikel Terkait

Tag:

Mungkin Anda juga menyukai

Tinggalkan Balasan

Alamat email Anda tidak akan dipublikasikan. Ruas yang wajib ditandai *