Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A Laravel queue job times out, the worker exits or the job runs twice

ErrorIlluminate\Queue\TimeoutExceededException

Short answer

A Laravel queue worker stops any job that runs longer than its timeout, 60 seconds by default, and exits with an error. Raise --timeout or the job's $timeout, keep it below the connection's retry_after so the job is not retried while still running, and make sure the PCNTL extension is installed.

  • Applies to Laravel 11, Laravel 12, PHP 8.3, Redis queue
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the worker in the foreground with an explicit timeout and watch what happens to the slow job. It shows whether the job is killed at the timeout or whether the job restarts.

    php artisan queue:work --timeout=120 --tries=1 -v
  2. 2Match what you see, then jump to its fix

    1. 1Long jobs die at about one minute and the worker process exitsThe job runs longer than the default 60-second timeoutFix
    2. 2A second worker starts the same job while the first is still runningThe timeout is not shorter than retry_after, so the job is picked up twiceFix
    3. 3Timeout options have no effect, and the PHP CLI has no pcntl functionsThe PCNTL extension is not installed, so timeouts cannot workFix
    4. 4The job hangs on an HTTP call or socket and only dies much laterA blocking call inside the job ignores the worker timeoutFix

What does the error look like?

  • Illuminate\Queue\TimeoutExceededException
  • Illuminate\Queue\MaxAttemptsExceededException
  • The same job starts a second time before the first one finished

Cause 1 of 4

The job runs longer than the default 60-second timeout

1Check

Laravel's default timeout is 60 seconds. A job's own $timeout property takes precedence over the command-line value.

grep -rn "timeout" app/Jobs
ps aux | grep "queue:work"

2Fix

Set a timeout big enough for the job, either on the worker or on the job class. The job property wins when both exist.

// app/Jobs/ProcessPodcast.php
class ProcessPodcast implements ShouldQueue
{
    public $timeout = 300;
}

# or for all jobs of this worker
php artisan queue:work --timeout=300

3Verify

Dispatch the slow job again and watch it finish without the worker exiting.

php artisan queue:work --once

Confirmed by laravel.com

Did this fix it?

Cause 2 of 4

The timeout is not shorter than retry_after, so the job is picked up twice

1Check

Laravel states that a job's timeout should always be less than the retry after value of the connection; the Redis example uses a default of 90 seconds.

grep -n "retry_after" config/queue.php

2Fix

Raise retry_after above the longest timeout, or lower the timeout. Then restart the workers so they read the new config.

// config/queue.php
'redis' => [
    'driver' => 'redis',
    'retry_after' => 360,   // longer than the 300 s job timeout
],

php artisan queue:restart

3Verify

Run a job that takes longer than the old retry_after; the log should show one attempt.

php artisan queue:work -v

Confirmed by laravel.com

Did this fix it?

Cause 3 of 4

The PCNTL extension is not installed, so timeouts cannot work

1Check

Laravel requires the PCNTL PHP extension to specify job timeouts.

php -m | grep -i pcntl

2Fix

Install or enable pcntl for the PHP CLI that runs the worker, then restart the worker.

php -m | grep -i pcntl

3Verify

The grep prints pcntl.

php -r 'var_dump(function_exists("pcntl_signal"));'

Confirmed by laravel.com

Did this fix it?

Cause 4 of 4

A blocking call inside the job ignores the worker timeout

1Check

Laravel warns that sockets and outgoing HTTP connections may not respect the worker timeout. Look for HTTP clients without their own timeout.

grep -rn "Http::\|new Client" app/Jobs

2Fix

Give the HTTP client its own connect and request timeouts, lower than the job timeout. The Laravel HTTP client already waits 10 seconds to connect and 30 seconds for a response by default.

Http::connectTimeout(5)->timeout(20)->get($url);

3Verify

Point the call at a slow host and confirm the job fails fast with a timeout exception.

php artisan queue:work --once -v

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Set $timeout on long jobs and $failOnTimeout when a timed-out job must not be retried.
  • Keep retry_after longer than the longest timeout on every connection.
  • Run workers under a process manager and restart them after each deploy with php artisan queue:restart.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

composer require maatwebsite/excel fails to install

Composer says the package needs an older PHP than the one installed

Composer refuses maatwebsite/excel when the PHP version or a PHP extension does not match what the package and PhpSpreadsheet need.

3 causes, each with a fix

Back end

composer require laravel/horizon fails: ext-pcntl is missing

laravel/horizon v1.1.0 requires ext-pcntl * -> the requested PHP extension pcntl is missing from your system

Horizon needs the pcntl extension, and Composer refuses to install it where PHP lacks that extension.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.