Maaz Zindani

Loading the index…

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

A Laravel job dispatched with delay() runs at once, or never runs

ErrorThe job runs immediately even though delay() was set

Short answer

A delayed job needs a real queue connection and a running worker. With the sync driver the job runs in the request, so the delay does nothing. With database or redis the job waits until a worker picks it up. SQS cannot delay longer than 15 minutes. Check QUEUE_CONNECTION first.

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

Fix it fast

  1. 1Find out which cause you have

    Read the queue connection the app really uses, after config caching.

    php artisan tinker --execute="echo config('queue.default');"
  2. 2Match what you see, then jump to its fix

    1. 1config('queue.default') prints syncThe sync driver executes the job at onceFix
    2. 2Rows stay in the jobs table past their delayNo queue worker is runningFix
    3. 3The queue is sqs and the delay is longer than 15 minutesSQS accepts a delay of at most 15 minutesFix
    4. 4New job code or changed delay has no effect until the worker is restartedThe worker still runs the old code after a deployFix

What does the error look like?

  • The job runs immediately even though delay() was set
  • The row stays in the jobs table and nothing happens
  • A delay of more than 15 minutes fails on SQS

Cause 1 of 4

The sync driver executes the job at once

1Check

The sync driver is meant for development and tests. It processes jobs inside the current PHP process and needs no worker.

grep -n QUEUE_CONNECTION .env

2Fix

Use a real connection. New Laravel apps default to database, which needs the jobs table.

# .env
QUEUE_CONNECTION=database

php artisan make:queue-table
php artisan migrate

3Verify

Dispatch a delayed job and see a row in jobs with a future available_at.

php artisan tinker --execute="echo DB::table('jobs')->count();"

Confirmed by laravel.com

Did this fix it?

Cause 2 of 4

No queue worker is running

1Check

Delayed and queued jobs are only processed while a worker runs. A delay only says when a job becomes available.

ps aux | grep "queue:work"

2Fix

Start a worker, and run it under a process monitor so it restarts after a crash.

php artisan queue:work

3Verify

The job runs once its delay has passed and the row disappears.

php artisan tinker --execute="echo DB::table('jobs')->count();"

Confirmed by laravel.com

Did this fix it?

Cause 3 of 4

SQS accepts a delay of at most 15 minutes

1Check

Amazon SQS has a maximum delay time of 15 minutes.

grep -n QUEUE_CONNECTION .env

2Fix

Use a delay of 15 minutes or less, or use a driver without that limit such as database or redis.

ProcessPodcast::dispatch($podcast)
    ->delay(now()->plus(minutes: 10));

3Verify

The job is accepted and runs after the delay.

php artisan queue:work sqs

Confirmed by laravel.com

Did this fix it?

Cause 4 of 4

The worker still runs the old code after a deploy

1Check

Workers are long-running processes and keep the code they loaded at start.

ps aux | grep "queue:work"

2Fix

Reload long-running services after each deploy, as the deployment guide describes.

php artisan reload

3Verify

The restarted worker runs the new code.

ps aux | grep "queue:work"

Confirmed by laravel.com

Did this fix it?

How do I stop it coming back?

  • Set QUEUE_CONNECTION explicitly in every environment, and keep sync for tests only.
  • Run workers under a process monitor, and reload them in the deploy script.
  • Keep SQS delays at 15 minutes or less.

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.