Fix laravel queue worker memory leak – detection & fix
Laravel queue workers can start fine, then slowly eat RAM until the process is killed or latency spikes. The symptom is a laravel queue worker memory leak that shows up as OOM errors in your logs. The fix is to spot the leak early, adjust the worker limits, and clean up the code that holds onto memory.
TL;DR / Quick Summary
Detect a leaky worker with php artisan horizon:status or ps -o rss,cmd -C php. Set restart_time (Horizon) or --timeout/--memory (Supervisor) to recycle after 5‑10 k jobs. Profile with Xdebug or Telescope, then remove static caches, close DB handles, and avoid long‑lived event listeners. The app stays under the PHP memory limit.
Reproducing a Minimal Leak
app/Jobs/LeakingJob.php
<?php
namespace App\Jobs;
use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Contracts\Queue\ShouldQueue;
class LeakingJob implements ShouldQueue
{
use Queueable, SerializesModels;
// ❌ static property that never resets
private static array $cache = [];
public function handle(): void
{
// Simulate heavy payload
$data = str_repeat('x', 1024 * 1024); // 1 MiB string
// Store it in static cache – memory never released
self::$cache[] = $data;
}
}Run it a few hundred times and watch ps – the PHP process climbs by megabytes each iteration.
Profiling the Leak
Xdebug command
php -d xdebug.mode=profile -d xdebug.start_with_request=trigger \
artisan queue:work --onceThe generated cachegrind.out.* file shows LeakingJob::handle allocating memory repeatedly.
Telescope shortcut
php artisan telescope:prune --hours=1 # keep recent entries only
php artisan queue:work --onceOpen Telescope → Jobs → inspect the memory column. A steady upward trend means a leak.
Config Tweaks to Contain the Damage
config/horizon.php (restart_time)
return [
'environments' => [
'production' => [
'supervisor-1' => [
'connection' => 'redis',
'queue' => ['default'],
'balance' => 'simple',
'processes' => 10,
// Restart after 5 000 jobs or 30 minutes, whichever comes first
'restart_time' => 30 * 60,
'memory' => 256, // MB per process
],
],
],
];Horizon will kill the worker and spawn a fresh one, preventing unbounded growth.
Supervisor config (laravel-worker.conf)
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan queue:work redis --sleep=3 --tries=3 --timeout=60 --memory=256
numprocs=8
autostart=true
autorestart=true
stopwaitsecs=3600
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/worker.log--memory=256 tells the worker to quit once it exceeds 256 MiB, letting Supervisor restart it.
Refactoring Common Leak Sources
Leak source | Why it leaks | Refactor tip |
|---|---|---|
Static properties | Data lives for the whole process lifetime | Replace with a short‑lived service container binding or clear the array at the end of |
Event listeners that stay registered | Queue workers never fire the Laravel bootstrapping that clears listeners | Register listeners inside the job or use |
Open file/DB handles without | PHP keeps the resource until script ends | Wrap DB calls in |
Example: Cleaning a static cache
public function handle(): void
{
$data = str_repeat('x', 1024 * 1024);
// Use a local variable instead of static
$temp = [$data];
// Process $temp …
// No lingering reference, memory freed automatically
}Common Pitfalls & Troubleshooting
Horizon ignores
restart_time– you’re runningqueue:workdirectly, nothorizon. Switch tophp artisan horizonor add the same--restartflag.Supervisor kills the process but the log shows “Memory limit exceeded” – the
--memoryflag is evaluated before the job finishes. Lower the limit or split the job into smaller chunks.Xdebug profile files fill the disk – enable
xdebug.output_dir=/tmp/xdebugand rotate them withlogrotate.Static caches survive across jobs even after
php artisan queue:restart– the restart only signals workers; they need to actually exit. Verify withpsthat old PIDs are gone.Event listeners added in a ServiceProvider – they persist for the whole worker lifecycle. Move them into the job’s
handleor useEvent::listenwith a closure that is discarded after the job.
FAQ
How can I see the current memory usage of a running queue worker? Run
ps -o pid,rss,cmd -C php | grep queue:work. The RSS column shows kilobytes used.Is the
--memoryoption the same as PHP'smemory_limit? No.--memoryis a Horizon/Supervisor guard that restarts the process;memory_limitis a PHP ini setting that throws a fatal error.Why does Telescope report high memory but the logs show no OOM? Telescope stores snapshots in the database; the snapshot size can inflate the reported value. Check the actual PHP process instead.
Can I rely on
php artisan queue:restartto fix leaks? It only signals workers to quit after the current job. If a job itself leaks, you still need to restart more frequently or refactor the job.
If you’ve hit a similar wall, check out our guide on Fix laravel queue workers stuck after deploy for additional restart strategies.
Connect with KoderSolution 🚀
Master modern software engineering, scalable architectures, and advanced backend systems with KoderSolution:
🌐 Official Website: Read more architectural deep-dives and tutorials on kodersolution.com
📺 YouTube Channel: Subscribe to @kodersolution on YouTube for concise, animated system design breakdowns and shorts.
📱 Facebook Page: Follow our official Facebook Page for daily development tips, architecture discussions, and community updates.
💬 What's your setup? What patterns have you used to keep Laravel queue workers lightweight in high‑throughput production, and how do you balance job granularity against restart overhead? Share your thoughts and join the discussion below!