Fix laravel queue worker memory leak – detection & fix

Avatar
M

Maksudur Rahman

Software Engineer•
2Views
5mRead
0Reactions

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 --once

The 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 --once

Open 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 handle

Event listeners that stay registered

Queue workers never fire the Laravel bootstrapping that clears listeners

Register listeners inside the job or use Event::forget() after handling

Open file/DB handles without close()

PHP keeps the resource until script ends

Wrap DB calls in DB::transaction() or explicitly $pdo = DB::connection()->getPdo(); $pdo = null;

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 running queue:work directly, not horizon. Switch to php artisan horizon or add the same --restart flag.

  • Supervisor kills the process but the log shows “Memory limit exceeded” – the --memory flag 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/xdebug and rotate them with logrotate.

  • Static caches survive across jobs even after php artisan queue:restart – the restart only signals workers; they need to actually exit. Verify with ps that old PIDs are gone.

  • Event listeners added in a ServiceProvider – they persist for the whole worker lifecycle. Move them into the job’s handle or use Event::listen with 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 --memory option the same as PHP's memory_limit? No. --memory is a Horizon/Supervisor guard that restarts the process; memory_limit is 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:restart to 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!

Maksudur Rahman
M
Written by•Software Engineer

Maksudur Rahman

Senior Developer Advocate & System Lead Moderator.

React to this article

Recommended Articles

View all articles