Laravel Queue sangat berguna untuk menjalankan proses berat di background, seperti mengirim email, memproses upload file, membuat laporan, mengirim notifikasi, atau menjalankan proses yang tidak perlu menunggu request HTTP selesai.

Namun, ada satu masalah yang cukup sering terjadi: job sudah di-dispatch, tetapi tidak kunjung diproses.

Kadang job tetap berada di Redis atau database. Kadang queue:work terlihat berjalan tetapi job tidak diproses. Pada server production, masalah juga bisa berasal dari Supervisor, konfigurasi .env, queue connection, worker yang belum direstart setelah deployment, atau job yang sebenarnya gagal.

Artikel ini membahas cara mengecek Laravel Queue yang tidak berjalan secara sistematis, mulai dari pemeriksaan konfigurasi sampai memastikan worker benar-benar memproses job.

Ringkasnya: jika Laravel Queue tidak berjalan, periksa QUEUE_CONNECTION, pastikan queue worker aktif, pastikan worker menggunakan connection dan queue yang benar, cek failed jobs/log Laravel, lalu periksa Supervisor jika aplikasi berjalan di production.

Penyebab Laravel Queue Tidak Berjalan

Beberapa penyebab yang paling umum adalah:

QUEUE_CONNECTION masih menggunakan konfigurasi yang tidak sesuai.
Queue worker belum dijalankan.
Worker menjalankan connection yang berbeda dari connection saat job di-dispatch.
Worker mendengarkan queue yang berbeda.
Redis atau database queue tidak dapat diakses.
Job masuk ke failed_jobs karena mengalami exception.
Supervisor tidak menjalankan atau tidak me-restart worker.
Worker masih menggunakan konfigurasi lama setelah perubahan .env.
Worker berhenti karena timeout atau masalah memory.
Aplikasi sedang dalam maintenance mode.
Kode Job berubah tetapi worker lama belum direstart.

Laravel menyediakan perintah php artisan queue:work untuk menjalankan worker yang memproses job dari queue. Worker tersebut merupakan proses yang berjalan terus-menerus, sehingga pada production biasanya diperlukan process monitor seperti Supervisor agar worker tetap berjalan.

1. Cek `QUEUE_CONNECTION`

Langkah pertama adalah memeriksa konfigurasi queue di file .env.

Contohnya jika menggunakan Redis:

QUEUE_CONNECTION=redis

Kemudian periksa konfigurasi queue Laravel:

php artisan config:show queue

Jika Anda menggunakan Laravel dengan Redis, pastikan konfigurasi Redis juga benar.

Contoh:

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

Nilai konfigurasi sebenarnya dapat berbeda tergantung setup server Anda.

Periksa apakah Redis berjalan

Jika menggunakan Redis sebagai queue backend, coba:

redis-cli ping

Jika Redis berjalan normal, biasanya hasilnya:

PONG

Jika muncul error seperti:

Could not connect to Redis

berarti masalahnya bukan pada worker Laravel terlebih dahulu, tetapi pada koneksi Laravel ke Redis.

Anda juga dapat memeriksa service Redis:

sudo systemctl status redis

Pada beberapa sistem, nama service dapat berbeda, misalnya redis-server.

2. Pastikan Queue Worker Sedang Berjalan

Setelah memastikan konfigurasi benar, jalankan worker secara manual:

php artisan queue:work

Jika menggunakan Redis secara eksplisit:

php artisan queue:work redis

Laravel menyediakan queue:work untuk menjalankan worker yang mengambil job dari queue dan memprosesnya. Worker akan terus berjalan sampai dihentikan.

Jika worker berjalan dan terdapat job di queue, Anda seharusnya mulai melihat job diproses.

Untuk mendapatkan informasi lebih detail, Anda dapat menggunakan:

php artisan queue:work -v

Output verbose dapat membantu melihat connection dan queue yang sedang digunakan oleh worker.

Jangan langsung menutup terminal

Jika Anda menjalankan:

php artisan queue:work

secara manual melalui SSH, worker tersebut bergantung pada session/terminal tempat proses tersebut dijalankan.

Untuk production, sebaiknya gunakan process manager seperti Supervisor sehingga worker dapat dipantau dan dijalankan kembali ketika berhenti.

3. Pastikan Connection yang Digunakan Sudah Benar

Ini adalah salah satu penyebab yang sering membuat developer mengira Laravel Queue rusak.

Misalnya Job dimasukkan ke Redis:

dispatch(new ProcessOrder);

tetapi worker yang dijalankan ternyata menggunakan connection lain.

Anda dapat menentukan connection secara eksplisit:

php artisan queue:work redis

Laravel juga memungkinkan Anda menentukan queue tertentu:

php artisan queue:work redis --queue=emails

Jika job dimasukkan ke queue emails, tetapi worker hanya mendengarkan queue yang berbeda, job tersebut tentu tidak akan diproses oleh worker tersebut. Laravel mendukung penentuan connection dan queue melalui opsi worker.

4. Pastikan Job Masuk ke Queue yang Benar

Perhatikan apakah Job Anda menggunakan queue tertentu.

Contoh:

dispatch(new SendWelcomeEmail)->onQueue('emails');

Job tersebut masuk ke queue:

emails

Maka worker harus mendengarkan queue tersebut:

php artisan queue:work redis --queue=emails

Jika Anda menjalankan:

php artisan queue:work redis

sementara konfigurasi default Anda tidak mengarah ke queue emails, job bisa tetap menunggu di queue.

Anda juga dapat menjalankan beberapa queue dengan prioritas:

php artisan queue:work redis --queue=high,default

Dengan konfigurasi tersebut, worker akan memprioritaskan queue high sebelum default.

5. Periksa Failed Jobs

Job yang terlihat seperti “tidak berjalan” sebenarnya bisa saja sudah dijalankan tetapi gagal.

Untuk melihat daftar failed jobs:

php artisan queue:failed

Jika terdapat job yang gagal, periksa detail errornya.

Laravel menyediakan mekanisme failed jobs untuk membantu mengetahui job yang tidak berhasil diproses setelah percobaan yang dikonfigurasi.

Setelah memperbaiki penyebab error, Anda dapat mencoba menjalankan ulang job yang gagal.

php artisan queue:retry all

Atau retry job tertentu:

php artisan queue:retry 5

Nomor 5 merupakan ID failed job, bukan ID dari model atau ID Job Anda.

6. Periksa Log Laravel

Jika worker berjalan tetapi Job gagal, periksa log Laravel.

Umumnya log berada di:

storage/logs/laravel.log

Anda dapat melihat log terbaru dengan:

tail -f storage/logs/laravel.log

Kemudian jalankan atau retry Job Anda.

Perhatikan error seperti:

SQLSTATE
Connection refused
Class not found
Allowed memory size exhausted
Maximum execution time exceeded
RedisException

Error tersebut biasanya memberikan petunjuk yang jauh lebih jelas mengenai penyebab Job gagal.

Jangan hanya melihat status worker

Worker yang aktif belum tentu berarti Job berhasil.

Misalnya:

Supervisor: RUNNING
Queue Worker: RUNNING

tetapi setiap Job ternyata mengalami exception.

Karena itu, ketika melakukan troubleshooting, periksa tiga hal:

Worker aktif?
        ↓
Job ditemukan?
        ↓
Job berhasil?

7. Pastikan Redis Bisa Diakses Laravel

Jika menggunakan Redis sebagai queue driver, Redis harus dapat diakses oleh aplikasi.

Tes Redis secara langsung:

redis-cli ping

Hasil normal:

PONG

Kemudian periksa konfigurasi Laravel:

php artisan config:show database

dan:

php artisan config:show queue

Jika aplikasi menggunakan Redis melalui host atau port tertentu, pastikan konfigurasi tersebut sesuai dengan server Redis Anda.

Contoh konfigurasi:

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Jika Redis berada di server/container berbeda, jangan menggunakan 127.0.0.1 kecuali memang Redis berada pada mesin yang sama dengan aplikasi.

8. Setelah Mengubah `.env`, Restart Worker

Ini adalah penyebab yang sering terlewat.

Laravel Queue Worker merupakan long-lived process. Artinya worker yang sudah berjalan tidak otomatis memuat ulang seluruh perubahan konfigurasi atau kode aplikasi hanya karena file .env atau source code berubah. Laravel merekomendasikan me-restart worker saat deployment.

Misalnya Anda mengubah:

QUEUE_CONNECTION=redis

tetapi worker sudah berjalan sejak sebelum perubahan tersebut.

Jangan hanya menjalankan:

php artisan config:clear

Kemudian menganggap worker otomatis menggunakan konfigurasi baru.

Restart worker secara graceful:

php artisan queue:restart

Perintah tersebut memberi sinyal kepada worker agar keluar setelah menyelesaikan Job yang sedang diproses. Setelah itu, process manager seperti Supervisor dapat menjalankan worker kembali.

Jika menggunakan Supervisor, biasanya Anda dapat melakukan:

sudo supervisorctl restart laravel-worker:*

Nama program tersebut harus disesuaikan dengan konfigurasi Supervisor Anda.

9. Periksa Supervisor

Pada production, Laravel Queue biasanya tidak cukup hanya dijalankan dengan:

php artisan queue:work

Anda membutuhkan process manager agar worker tetap berjalan.

Supervisor merupakan salah satu pilihan yang umum digunakan pada server Linux. Dokumentasi Laravel juga merekomendasikan process monitor seperti Supervisor untuk menjaga queue:work tetap berjalan.

Periksa status Supervisor:

sudo supervisorctl status

Contohnya:

laravel-worker:laravel-worker_00   RUNNING
laravel-worker:laravel-worker_01   RUNNING

Jika statusnya:

STOPPED

atau:

FATAL

berarti worker tidak berjalan sebagaimana mestinya.

Setelah mengubah konfigurasi Supervisor

Jalankan:

sudo supervisorctl reread
sudo supervisorctl update

Kemudian:

sudo supervisorctl restart laravel-worker:*

Jika nama program Supervisor Anda berbeda, sesuaikan perintah tersebut dengan konfigurasi yang digunakan.

10. Periksa `command` Supervisor

Contoh konfigurasi Supervisor untuk Laravel Queue:

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/example.com/artisan queue:work redis --sleep=3 --tries=3
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/example.com/storage/logs/worker.log
stopwaitsecs=3600

Bagian yang paling penting adalah:

command=php /var/www/example.com/artisan queue:work redis --sleep=3 --tries=3

Pastikan path Laravel benar.

Misalnya aplikasi sebenarnya berada di:

/var/www/myapp

tetapi Supervisor menggunakan:

/var/www/example.com

worker tidak akan bekerja dengan benar.

Periksa juga user yang digunakan:

user=www-data

Pastikan user tersebut mempunyai permission yang sesuai untuk menjalankan aplikasi Laravel.

11. Periksa Log Supervisor

Jika Supervisor langsung berubah menjadi FATAL, jangan hanya melakukan restart berulang kali.

Periksa log Supervisor:

sudo tail -f /var/log/supervisor/supervisord.log

Kemudian periksa log worker jika Anda mengarahkannya ke file tertentu:

tail -f storage/logs/worker.log

Kesalahan pada path PHP, path Artisan, permission, environment, atau command worker biasanya dapat ditemukan dari sini.

12. Pastikan PHP CLI yang Digunakan Benar

Ini juga sering terjadi pada server yang mempunyai beberapa versi PHP.

Periksa versi PHP:

php -v

Kemudian:

which php

Misalnya hasilnya:

/usr/bin/php

Bandingkan PHP yang digunakan oleh terminal dengan PHP yang digunakan Supervisor.

Anda juga dapat menjalankan:

/usr/bin/php /var/www/example.com/artisan queue:work redis

Jika cara tersebut berhasil tetapi konfigurasi Supervisor tidak berhasil, kemungkinan masalah ada pada environment atau command Supervisor.

13. Periksa Permission Laravel

Laravel membutuhkan akses tulis pada direktori tertentu, terutama:

storage
bootstrap/cache

Periksa permission:

ls -la storage

dan:

ls -la bootstrap/cache

Jika worker dijalankan menggunakan user tertentu, pastikan user tersebut dapat mengakses file dan direktori yang dibutuhkan aplikasi.

Contoh perbaikan permission yang umum:

sudo chown -R www-data:www-data storage bootstrap/cache

Namun jangan menjalankan perintah permission secara sembarangan pada seluruh project. Sesuaikan dengan user dan struktur deployment Anda.

14. Periksa Apakah Aplikasi Sedang Maintenance Mode

Secara default, Laravel tidak memproses queued jobs ketika aplikasi berada dalam maintenance mode.

Jika worker berjalan tetapi Job tidak diproses, periksa status aplikasi.

Jika memang aplikasi sedang maintenance dan Anda ingin worker tetap memproses queue, Laravel menyediakan opsi:

php artisan queue:work --force

Menurut dokumentasi Laravel, opsi --force dapat digunakan agar worker tetap memproses Job ketika maintenance mode aktif.

Gunakan opsi ini hanya jika memang sesuai dengan kebutuhan deployment Anda.

15. Periksa Timeout Job

Job yang membutuhkan waktu lama juga dapat mengalami masalah apabila timeout worker terlalu pendek.

Misalnya Job Anda melakukan proses:

membuat laporan PDF,
memproses video,
mengolah ribuan data,
mengirim banyak request API,
atau melakukan operasi file besar.

Anda dapat mengatur timeout worker:

php artisan queue:work redis --timeout=120

Artinya worker diberi waktu sampai sekitar 120 detik untuk sebuah Job sebelum timeout worker tercapai.

Namun jangan sekadar menaikkan timeout untuk menghilangkan error.

Cari tahu terlebih dahulu mengapa Job membutuhkan waktu lama.

Job yang terlalu berat sering kali lebih baik dipecah menjadi beberapa Job kecil.

16. Periksa Memory Worker

Queue worker adalah proses jangka panjang. Jika Job tertentu menggunakan memory besar, penggunaan memory worker dapat meningkat selama worker berjalan.

Laravel menyediakan opsi seperti:

php artisan queue:work redis --memory=256

Anda juga dapat membatasi jumlah Job yang diproses worker:

php artisan queue:work redis --max-jobs=1000

atau membatasi waktu worker:

php artisan queue:work redis --max-time=3600

Opsi seperti --max-jobs dan --max-time dapat digunakan bersama process manager agar worker keluar secara terkontrol dan kemudian dijalankan kembali.

Cara Troubleshooting Laravel Queue Secara Cepat

Jika Anda tidak tahu harus mulai dari mana, gunakan urutan berikut.

Langkah 1 — Periksa connection

php artisan config:show queue

Pastikan connection yang digunakan sesuai dengan konfigurasi aplikasi.

Langkah 2 — Jalankan worker manual

php artisan queue:work -v

Jika Job langsung diproses, kemungkinan masalah ada pada Supervisor atau process manager.

Langkah 3 — Periksa failed jobs

php artisan queue:failed

Jika ada Job yang gagal, periksa exception-nya.

Langkah 4 — Periksa Laravel log

tail -f storage/logs/laravel.log

Langkah 5 — Jika menggunakan Redis

redis-cli ping

Pastikan hasilnya:

PONG

Langkah 6 — Jika menggunakan Supervisor

sudo supervisorctl status

Pastikan worker berstatus:

RUNNING

Langkah 7 — Setelah deployment

Jalankan:

php artisan queue:restart

Kemudian pastikan Supervisor menjalankan worker kembali.

Contoh Alur Debugging

Misalnya Anda mempunyai Job:

SendInvoiceEmail::dispatch($invoice);

Tetapi email tidak pernah dikirim. Jangan langsung mengubah kode Job. Ikuti alur berikut.

1. Pastikan Job memang menggunakan queue

Periksa:

QUEUE_CONNECTION=redis

2. Pastikan Redis hidup

redis-cli ping

Hasil:

PONG

3. Jalankan worker

php artisan queue:work redis -v

4. Dispatch Job lagi

SendInvoiceEmail::dispatch($invoice);

5. Perhatikan output worker

Jika Job diproses tetapi gagal, periksa:

php artisan queue:failed

Kemudian:

tail -f storage/logs/laravel.log

6. Jika worker manual berhasil

Jika:

php artisan queue:work redis

berhasil memproses Job, tetapi Job tidak berjalan ketika worker dikelola Supervisor, fokuskan pemeriksaan pada:

konfigurasi Supervisor,
path project,
path PHP,
user Supervisor,
environment,
permission,
dan log Supervisor.

Dengan cara ini Anda tidak perlu mengubah banyak konfigurasi secara acak.

Checklist Laravel Queue Tidak Berjalan

Sebelum menyimpulkan bahwa Laravel Queue bermasalah, periksa semua poin berikut:

[ ] QUEUE_CONNECTION sudah benar
[ ] Redis/database queue dapat diakses
[ ] Queue worker sedang berjalan
[ ] Worker menggunakan connection yang benar
[ ] Worker mendengarkan queue yang benar
[ ] Job tidak masuk failed_jobs
[ ] storage/logs/laravel.log tidak menunjukkan error
[ ] Supervisor berstatus RUNNING
[ ] Command Supervisor menggunakan path Laravel yang benar
[ ] PHP CLI yang digunakan sudah benar
[ ] Permission storage dan bootstrap/cache sesuai
[ ] Worker sudah direstart setelah perubahan deployment
[ ] Timeout Job cukup
[ ] Memory worker tidak bermasalah
[ ] Aplikasi tidak sedang maintenance mode

Kesimpulan

Ketika Laravel Queue tidak berjalan, jangan langsung menganggap Redis atau Laravel mengalami kerusakan.

Mulailah dari hal yang paling sederhana:

QUEUE_CONNECTION
      ↓
Queue backend
      ↓
queue:work
      ↓
Connection & Queue
      ↓
Failed Jobs
      ↓
Laravel Log
      ↓
Supervisor
      ↓
PHP / Permission / Timeout / Memory

Untuk development, menjalankan:

php artisan queue:work

biasanya sudah cukup untuk menguji apakah worker dapat memproses Job.

Sedangkan pada production, worker sebaiknya dijalankan menggunakan process monitor seperti Supervisor agar proses dapat dipantau dan dijalankan kembali ketika berhenti. Laravel juga menyarankan restart worker setelah deployment karena queue worker merupakan proses jangka panjang.

Jika Anda menggunakan Laravel + Redis + Supervisor, tiga perintah berikut adalah titik awal troubleshooting yang sangat berguna:

php artisan queue:work redis -v

php artisan queue:failed

sudo supervisorctl status

Dari ketiga pemeriksaan tersebut, biasanya sudah dapat diketahui apakah masalah berada pada queue worker, Job, Redis, atau Supervisor.

FAQ

Kenapa Laravel Queue tidak memproses Job?

Penyebab paling umum adalah worker belum berjalan, connection berbeda, queue yang didengarkan berbeda, backend queue tidak dapat diakses, atau Job mengalami error. Mulailah dengan menjalankan php artisan queue:work -v dan periksa php artisan queue:failed.

Kenapa `php artisan queue:work` berjalan tetapi Job tidak diproses?

Periksa apakah Job masuk ke queue yang benar. Jika Job menggunakan queue seperti emails, worker juga harus mendengarkan queue tersebut, misalnya:

php artisan queue:work redis --queue=emails

Kenapa Laravel Queue berhenti setelah server restart?

Jika worker hanya dijalankan melalui terminal, proses tersebut tidak otomatis menjadi service yang persisten. Pada production, gunakan process manager seperti Supervisor untuk menjaga worker tetap berjalan.

Kenapa Laravel Queue tidak menggunakan konfigurasi `.env` terbaru?

Queue worker merupakan long-lived process. Setelah mengubah konfigurasi, worker yang sudah berjalan mungkin masih menggunakan state lama. Restart worker dengan:

php artisan queue:restart

dan pastikan process manager menjalankannya kembali.

Bagaimana mengetahui apakah Laravel Queue mengalami error?

Periksa:

php artisan queue:failed

dan log:

tail -f storage/logs/laravel.log

Jika menggunakan Supervisor, periksa juga log Supervisor dan log worker.

Penyebab Laravel Queue Tidak Berjalan

1. Cek QUEUE_CONNECTION

Periksa apakah Redis berjalan

2. Pastikan Queue Worker Sedang Berjalan

Jangan langsung menutup terminal

3. Pastikan Connection yang Digunakan Sudah Benar

4. Pastikan Job Masuk ke Queue yang Benar

5. Periksa Failed Jobs

6. Periksa Log Laravel

Jangan hanya melihat status worker

7. Pastikan Redis Bisa Diakses Laravel

8. Setelah Mengubah .env, Restart Worker

9. Periksa Supervisor

Setelah mengubah konfigurasi Supervisor

10. Periksa command Supervisor

11. Periksa Log Supervisor

12. Pastikan PHP CLI yang Digunakan Benar

13. Periksa Permission Laravel

14. Periksa Apakah Aplikasi Sedang Maintenance Mode

15. Periksa Timeout Job

16. Periksa Memory Worker

Cara Troubleshooting Laravel Queue Secara Cepat

Langkah 1 — Periksa connection

Langkah 2 — Jalankan worker manual

Langkah 3 — Periksa failed jobs

Langkah 4 — Periksa Laravel log

Langkah 5 — Jika menggunakan Redis

Langkah 6 — Jika menggunakan Supervisor

Langkah 7 — Setelah deployment

Contoh Alur Debugging

1. Pastikan Job memang menggunakan queue

2. Pastikan Redis hidup

3. Jalankan worker

4. Dispatch Job lagi

5. Perhatikan output worker

6. Jika worker manual berhasil

Checklist Laravel Queue Tidak Berjalan

Kesimpulan

FAQ

Kenapa Laravel Queue tidak memproses Job?

Kenapa php artisan queue:work berjalan tetapi Job tidak diproses?

Kenapa Laravel Queue berhenti setelah server restart?

Kenapa Laravel Queue tidak menggunakan konfigurasi .env terbaru?

Bagaimana mengetahui apakah Laravel Queue mengalami error?

1. Cek `QUEUE_CONNECTION`

8. Setelah Mengubah `.env`, Restart Worker

10. Periksa `command` Supervisor

Kenapa `php artisan queue:work` berjalan tetapi Job tidak diproses?

Kenapa Laravel Queue tidak menggunakan konfigurasi `.env` terbaru?