DEV Community: laravel-o11y

Laravel Job timeout vs retry_after: The Ordering Rule Nothing Enforces

laravel-o11y — Fri, 18 Sep 2026 07:20:24 +0000

Two numbers, in two different configuration files, decide whether a queued job runs once or twice. One is retry_after, in config/queue.php. The other is your worker's timeout, in config/horizon.php or on the job class itself. Laravel ships them 30 seconds apart and mentions the relationship twice in prose. No code checks it at boot, at dispatch, or when a supervisor starts a worker.

Get the order wrong and a job that is still running is handed to a second worker. What you see next depends on a third setting, tries. Either two workers execute the same job concurrently and both report success, or a job you never saw run twice lands in your failed jobs list with MaxAttemptsExceededException, for work that completed. The rest of this article covers the mechanism behind both symptoms, the exact defaults, and the ordering rule you have to enforce yourself.

Key takeaways

retry_after is a lease, not a delay. Popping a job reserves it for retry_after seconds. When the lease expires the job goes back on the ready queue whether or not it is still running.
The defaults are 60 and 90, if you kept the shipped config. Worker timeout defaults to 60s, the shipped retry_after to 90s. Omit retry_after from a connection and the framework falls back to 60, making the two equal.
Equal values are not safe. The lease starts at pop() and the timeout alarm is armed a few steps later, so with matching values the reservation always expires first.
The symptom depends on tries. With tries => 1 (the value in Horizon's published config) you get a failure recorded against a job that succeeded. With tries => 2 or more you get concurrent double execution, and nothing fails.
The rule: job timeout < supervisor timeout < retry_after, with margin at each step. Nothing in Laravel tells you when it stops holding.

The two numbers and their defaults

Both settings are measured in seconds and are easy to confuse. retry_after belongs to the queue connection and sets how long a reservation is honoured. timeout belongs to the worker and sets how long a single job may occupy a process. They have different owners, run on different clocks, and nothing enforces a relationship between them.

	`timeout`	`retry_after`
Owned by	The worker process (or the job class)	The queue connection
Configured in	`config/horizon.php`, `--timeout`, `$timeout`, `#[Timeout]`	`config/queue.php`
Default	60 (`queue:work --timeout=60`, and the Horizon supervisor default)	90 as shipped in `config/queue.php`; 60 if the key is absent
Enforced by	`pcntl_alarm()` in the worker	A score on the reserved set, checked by whichever worker pops next
On expiry	The worker kills itself	The job becomes available to everyone again

A stock Laravel skeleton pairs a 60-second timeout with a 90-second retry_after, which is a correct configuration with 30 seconds of slack. But the 90 is a value in your configuration file, not a framework default. The framework's own fallback, used whenever a connection array has no retry_after key, is 60:

// Illuminate\Queue\Connectors\RedisConnector
return new RedisQueue(
    $this->redis, $config['queue'],
    Arr::get($config, 'connection', $this->connection),
    Arr::get($config, 'retry_after', 60),   // not 90
    // ...
);

A connection written by hand (a second Redis connection for a dedicated queue, a connection built in a test, anything copied from a blog post rather than from config/queue.php) gets 60 with no warning, equal to the default worker timeout. That configuration is broken from the first job that runs long, and it looks reasonable in a pull request.

What `retry_after` does

The name suggests a delay before a retry. It is a lease: popping the job sets a deadline on its reservation, and once that deadline passes any worker can take the job, including while the first worker is still running it.

On Redis, popping a job is a single Lua script. It lpops the payload off the ready list, increments the payload's attempts counter, and adds the result to a sorted set, scored with the moment the reservation expires:

-- Illuminate\Queue\LuaScripts::pop()
local job = redis.call('lpop', KEYS[1])
local reserved = false

if(job ~= false) then
    -- Increment the attempt count and place job on the reserved queue...
    reserved = cjson.decode(job)
    reserved['attempts'] = reserved['attempts'] + 1
    reserved = cjson.encode(reserved)
    redis.call('zadd', KEYS[2], ARGV[1], reserved)
    redis.call('lpop', KEYS[3])
end

ARGV[1] is now + retry_after. No timer watches that score. Instead, every pop() on that queue begins by sweeping it:

// Illuminate\Queue\RedisQueue
public function pop($queue = null, $index = 0)
{
    $this->migrate($prefixed = $this->getQueueRedisKey($queue));
    // ...
}

migrate() moves two things back onto the ready list: delayed jobs whose time has come, and reserved jobs whose lease has expired. It cannot tell the difference between a job whose worker was killed by a deploy and a job whose worker is still running it. Both look like an expired score.

The database driver reaches the same outcome through SQL rather than a sorted set. isReservedButExpired() widens the "next available job" query to include any row whose reserved_at is older than now - retry_after, so it also has no way to know whether the original worker is alive.

Two drivers behave differently. Beanstalkd has no retry_after default of its own and falls back to Pheanstalk's TTR. SQS has no retry_after at all: the connector never reads the key, because the lease lives on Amazon's side as the queue's Default Visibility Timeout. Its default is 30 seconds, half of Laravel's default worker timeout. An SQS queue created with the console defaults and consumed by a stock worker is misconfigured from the start, and no edit to config/queue.php will fix it.

What `timeout` does

The worker's timeout is independent of the queue. It is a POSIX alarm, set per job, inside the worker process:

// Illuminate\Queue\Worker::registerTimeoutHandler()
pcntl_signal(SIGALRM, function () use ($job, $options) {
    // ...record the failure, dispatch JobTimedOut...
    $this->kill(static::$timedOutExitCode ?? static::EXIT_ERROR, $options, WorkerStopReason::TimedOut);
}, true);

pcntl_alarm(
    max($this->timeoutForJob($job, $options), 0)
);

Three consequences follow from this code, and each can break the ordering rule without anyone touching config/queue.php:

The job's own timeout takes precedence. timeoutForJob() returns the job's $timeout property or #[Timeout] attribute if it has one, and only falls back to the worker's option. A single #[Timeout(300)] on a slow report job overrides a correctly configured 60-second supervisor and outlasts a 90-second lease.
--timeout=0 disables it. pcntl_alarm(0) cancels the alarm rather than firing immediately, so a zero timeout means no timeout. Nothing bounds the job's runtime, while the lease keeps expiring on schedule.
Without pcntl there is no timeout. The handler sits behind a supportsAsyncSignals() check. On a build without the extension no alarm is set and nothing reports that, so long jobs are duplicated with no local symptom to reproduce.

Why the two collide, and why equal values fail

Take a 90-second job with retry_after and timeout both set to 90, a configuration that looks tidy in a config file:

t=0.00   worker A pops the job; reservation scored to expire at t=90.00
t=0.02   JobReserved fires, the worker enters process()
t=0.03   pcntl_alarm(90) armed, will fire at t=90.03
t=90.00  worker B pops the same queue; migrate() sees an expired score
         and moves the still-running job back onto the ready list
t=90.00  worker B pops it, attempts becomes 2
t=90.03  worker A's alarm fires, 30ms after worker B took the job

The lease starts at the pop. The alarm is armed several steps later: after the reservation is written, after the JobReserved event and its listeners run, and after the worker enters process(). With identical values the reservation expires first every time, by the length of that setup. Even when the alarm does fire first, the handler still has to record the failure and exit before the process lets go of anything.

This is also why the bug is hard to reproduce. Migration is lazy: it only happens when somebody pops that queue. A supervisor with a single worker, occupied by the long job, never sweeps its own expired reservation, so the misconfiguration stays invisible until a second worker exists. Autoscale from one process to two, or move from a laptop to production, and the same code starts running jobs twice.

The two symptoms, and which one you get

Once the job has been migrated back and popped by a second worker, tries decides what happens next. The Lua script incremented attempts on that second pop, and Worker::process() checks the attempt count before it fires the job:

// Illuminate\Queue\Worker::process()
$this->raiseBeforeJobEvent($connectionName, $job);

$this->markJobAsFailedIfAlreadyExceedsMaxAttempts(
    $connectionName, $job, (int) $options->maxTries
);

// ...

$job->fire();

With `tries => 1`: a failure on work that succeeded

One attempt is what most Horizon installs run with: the config/horizon.php that Horizon publishes sets 'tries' => 1 on its supervisor, and a job class with no $tries of its own inherits it. (Drop the key entirely and horizon:supervisor falls back to --tries=0, which means unlimited.) The migrated copy arrives at worker B carrying attempts = 2, exceeds the limit before fire() is reached, and is failed immediately with MaxAttemptsExceededException. Its body never runs.

There is no duplicate execution, but you now have a failed job in the dashboard for work that is still running and completes successfully a few seconds later. Worker A finishes, tries to delete its reservation, and removes nothing, because the entry was migrated away while it worked. The same job id ends up with one failure and one success, and the stack trace points at a timeout that never happened.

If you have chased "MaxAttemptsExceededException on a job that clearly worked", this is one of two ways to get there. The other is lock-based middleware spending attempts on releases, which has its own set of failure modes.

With `tries => 2` or more: concurrent execution with no error

Most applications raise tries eventually, because retries are the point of a queue and because middleware like RateLimited and WithoutOverlapping consume attempts. With two or more attempts allowed, the check passes, and worker B calls fire() while worker A is inside the same job's handle().

Both copies run to completion, so the card is charged twice or the email goes out twice. Neither copy throws or is marked failed, and the dashboard shows one completed job. Laravel, Horizon and your error tracker record nothing unusual. The evidence is in your data, as duplicate rows, doubled counters or a customer with two receipts.

Four ways a correct config becomes an incorrect one

timeout usually ends up above retry_after as a side effect of a change that looked local:

A job gained a timeout of its own. A nightly export starts taking four minutes, someone adds #[Timeout(300)] to the job class, and the supervisor's 60 no longer applies to that job while the connection's 90-second lease is unchanged. The job class is the highest-precedence setting and the one furthest from the config file where the constraint lives.
A supervisor timeout was raised to fix timeouts. Jobs are being killed at 60 seconds, so the supervisor timeout goes to 120. The kills stop and the lease problem above starts, because retry_after is in a different file and was not part of the change.
A new connection was added without the key. It gets the 60-second framework fallback described above. The values are equal from the first deploy, and the diff contains no line that would catch it.
The queue moved to SQS. The lease is now a Default Visibility Timeout of 30 seconds set on the AWS side, and config/queue.php has no say in it.

The opposite mistake is setting 'retry_after' => null on a Redis connection. That skips reserved-job migration altogether, so a job whose worker dies is never recovered. You avoid duplicates and lose jobs instead, with no error to show for it.

The ordering rule, with numbers

The full chain has three links, because Horizon's supervisor timeout is a separate value from the job's, and with balance => 'auto' Horizon force-kills workers it considers hung during scale-down:

job timeout < supervisor timeout < retry_after

Each step needs more than a second of headroom. A worked example for a job whose realistic worst case is three minutes:

Setting	Value	Why
Realistic worst-case runtime	180s	Measured: the p99 from your own metrics
Job `#[Timeout]`	240s	Above the worst case, so normal runs are never killed
Supervisor `timeout`	300s	Above every job timeout in the supervisor, so scale-down does not kill live work
Connection `retry_after`	390s	Above the supervisor timeout, plus room for the alarm handler to finish and exit

Over-shooting retry_after has a small, bounded cost: a job whose worker did die waits longer before it is recovered. Under-shooting it causes duplicate execution, so when in doubt, make the lease longer.

A supervisor serves one connection, so you can check the constraint in a test:

// tests/Feature/QueueTimeoutOrderingTest.php
public function test_supervisor_timeouts_stay_below_their_connection_lease(): void
{
    foreach (config('horizon.defaults') as $name => $supervisor) {
        $connection = $supervisor['connection'];

        // The 60 mirrors the framework's own fallback when the key is absent.
        $retryAfter = config("queue.connections.{$connection}.retry_after", 60);

        $this->assertLessThan(
            $retryAfter,
            $supervisor['timeout'] ?? 60,
            "Supervisor [{$name}] can hand a running job to a second worker.",
        );
    }
}

The test covers supervisors. It cannot see a $timeout property or a #[Timeout] attribute on an individual job class, which is the most common way the chain breaks. Those you can only catch at runtime, when the worker resolves the effective timeout for the job in front of it.

Skyline runs the supervisor half of that check for you: php artisan horizon warns at startup about any supervisor whose timeout is not below its connection's retry_after.

Catching it in the logs

This misconfiguration can survive in production for months because the queue's own instrumentation reports it as ordinary activity. An expired reservation looks like a recovered job, and a second worker picking the job up looks like any other pickup.

Skyline's job lifecycle logging writes one line per transition, tagged with the job id, including the transitions Laravel does not log: reserved, migrated, released and timed out. When a job leaves the reserved set because its lease ran out, the line is a warning that names the cause, and the pattern to look for is a single job id reserved twice with that warning between the two reservations:

[11:04:12] queue.DEBUG: [job:91827364] reserved from [exports] and started processing.
[11:05:42] queue.WARNING: [job:91827364] was still reserved on [exports] when its reservation expired (retry_after=90s) and has been put back on the queue. Either the worker running attempt 1 died, or the job runs longer than retry_after and this copy will run while the first is still going; keep every job's timeout below retry_after (reason=reservation_expired).
[11:05:45] queue.DEBUG: [job:91827364] reserved from [exports] and started processing.
[11:06:20] queue.DEBUG: [job:91827364] completed.

The job was picked up at 11:04:12. Ninety seconds later, still running because no completion line had appeared, it was put back on the ready queue and picked up again three seconds after that. A grep for the job id is enough to tell a retry from a double reservation, which the dashboard alone cannot do. The reserved lines are debug, so enable that level on the channel for the investigation and turn it off afterwards; the expired-reservation line is a warning and can stay on permanently.

Common questions

What is retry_after in Laravel queues?

It is a lease on a reserved job, not a delay before a retry. Popping a job writes it to the connection's reserved set with an expiry of now plus retry_after seconds. Every later pop on that queue first sweeps that set and moves anything expired back onto the ready queue, whether or not the worker that reserved it is still running it. Nothing checks the original worker is alive, so an expired lease on a live job looks the same as one on a worker killed by a deploy.

What are the default values of timeout and retry_after?

The worker timeout defaults to 60 seconds. That is the default of queue:work --timeout, queue:listen --timeout and the Horizon supervisor timeout option. retry_after is 90 seconds in the config/queue.php that ships with the Laravel skeleton, but the framework's own fallback, used whenever a connection array omits the key, is 60. SQS has no retry_after at all; its lease is the queue's Default Visibility Timeout on the AWS side, which defaults to 30 seconds.

Why is my Laravel job running twice?

Almost always because its effective timeout is not smaller than the connection's retry_after, so the reservation expires while the job is still running and a second worker picks the same payload up. The effective timeout may not be the one in your supervisor config: a $timeout property or #[Timeout] attribute on the job class takes precedence, and --timeout=0 disables the alarm entirely rather than firing it immediately.

Is it safe to set timeout equal to retry_after?

No. The reservation clock starts at pop(), while the timeout alarm is armed several steps later: after the reservation is written, after JobReserved and its listeners run, and after the worker enters process(). With identical values the reservation expires first every time, and the alarm handler still has to record the failure and exit after that.

Why did my job fail with MaxAttemptsExceededException when it actually succeeded?

Because the reserved copy was migrated back and popped by a second worker, and the pop incremented the attempt count. With tries set to 1, as in the config/horizon.php that Horizon publishes, the second copy exceeds its limit before fire() is reached and is failed immediately, while the first copy is still running and goes on to complete. With tries above 1 the attempt check passes and both copies execute, with no failure recorded to tell you.

Laravel Horizon Queue Balancing: Idle Workers vs. Starved Queues

laravel-o11y — Sun, 13 Sep 2026 16:51:50 +0000

Every Horizon supervisor makes you choose. Turn balancing on and you pay for a floor of idle workers. Turn it off and a busy queue starves the queues listed after it. The more queues you run, the more each option costs, and many teams find this out only when a flood on one queue stalls all the others.

This article explains where the trade-off comes from, why running many small queues makes it worse, and how Skyline's weighted queues give you a shared pool of workers without starvation.

Key takeaways

Balancing on ('auto' or 'simple') gives every queue its own worker pool. Nothing starves, but you pay a permanent floor of resident workers that scales with your queue count.
Balancing off (false) runs one shared pool with no idle floor, but the queue list becomes a strict priority order, so a flood on one queue starves every queue below it.
Both costs scale with the number of queues, which penalises the teams who split work into many queues to get per-queue pausing, draining and visibility.
Skyline's queueWeights keeps the shared pool of unbalanced mode but checks queues in proportion to their weights (3 : 2 : 1) rather than in strict order. Important work gets most of the pickups and no queue drops to zero.

Why you end up with thirty queues in the first place

A queue is the smallest unit Horizon lets you observe and operate on, and Laravel's queue:pause and queue:clear commands both act on one queue at a time. So when you want operational control ("show me how exports is doing", "pause webhooks while the downstream API is down", "empty the reindex backlog without touching payments"), you split work into more, narrower queues. (Skyline adds pausing and resuming a single queue from the dashboard rather than the whole supervisor.)

That is how a healthy app ends up with thirty queues: payments, emails, webhooks-stripe, webhooks-github, exports, imports, reindex, thumbnails, and on down the list. Each one gets its own dashboard row and its own pause and drain switch.

Both balancing modes have a cost that grows with the number of queues, so the teams that split work most finely pay the most.

Option A: `balance => 'auto'` and the idle-worker floor

With balance => 'auto' (or 'simple'), Horizon allocates worker processes per queue. The auto balancer scales each queue's worker count up and down with its workload, but never below minProcesses, which defaults to 1:

'supervisor-1' => [
    'connection'   => 'redis',
    'queue'        => ['payments', 'emails', 'exports', /* ...27 more */],
    'balance'      => 'auto',
    'minProcesses' => 1,
    'maxProcesses' => 40,
],

minProcesses guarantees that every queue always has at least one worker watching it, so a flood on exports can't prevent payments from being serviced. Each queue is isolated, and for many setups that makes this the right default.

The cost is that one minimum worker per queue across thirty queues is a permanent floor of thirty worker processes. They are booted, resident, and idle most of the time, because most queues are empty most of the time. Each PHP worker is a full framework boot holding tens of megabytes of RAM whether or not it ever picks up a job.

The floor also counts against your ceiling. If minProcesses across thirty queues already pins thirty workers and maxProcesses is 40, the auto balancer has only ten processes left for the queue that is busy. Raising maxProcesses gives that queue more room, but the thirty idle workers are still there.

Option B: `balance => false` and starvation by list order

With balance => false, Horizon runs a single shared pool of workers. Every worker listens to every queue and checks them in the order you listed them. There is no per-queue floor and no idle minimum, and workers go wherever the work is. On paper this is the efficient option:

'supervisor-1' => [
    'connection'   => 'redis',
    'queue'        => ['high', 'default', 'low'],
    'balance'      => false,
    'maxProcesses' => 10,
],

The problem is the list order. Without balancing, the queue list is a strict left-to-right priority. A worker only looks at default when high is empty, and only looks at low when both are empty. Under light load you won't notice. Under sustained load, the order decides who gets served at all:

A flood on a higher-priority queue starves every queue below it until the flood drains.

Push fifty thousand jobs onto high and every worker in the pool works on it. default and low get no workers for as long as high stays non-empty. Dropping the idle-worker floor cost you the isolation that balancing guaranteed.

What is the difference between `balance` auto, simple and false?

Horizon ships two balancing strategies and an off switch. The two strategies are closer than most people assume: both 'auto' and 'simple' give every queue its own pool of worker processes, and they differ only in whether that allocation can move.

'simple' splits the supervisor's processes evenly across the queues in the list and leaves them there. Ten processes across two queues means five each, even if one of them has been empty all day.
'auto' starts from the same per-queue pools but continuously reallocates them to match each queue's workload, scaling a busy queue up toward maxProcesses and a quiet one down to minProcesses. (Whether "workload" means queue size or estimated time-to-clear is configurable via autoScalingStrategy.)
false is not a balancing strategy. There are no per-queue pools: one shared pool of workers listens to every queue and checks them in the order you listed them.

Side by side, with Skyline's weighted mode in the last column:

	`'simple'`	`'auto'`	`false`	`false` + weights
Worker pools	One per queue, fixed even split	One per queue, resized to load	One shared pool	One shared pool
Idle-worker floor	`maxProcesses` ÷ queues, always resident	`minProcesses` per queue (defaults to 1)	None	None
Can a queue starve?	No	No	Yes, strict list order	No, every queue keeps a share
Priority model	None (even split)	None (load-driven)	Strict left-to-right	Proportional (3 : 2 : 1)
Adds capacity to a spike	No	Yes, scales processes up	Shared pool absorbs it	Shared pool absorbs it

The upstream reference for the two strategies is the Horizon balancing documentation.

Why the trade-off gets worse with every queue you add

The two options are mirror images:

Balancing on gives you isolation (no queue starves) and charges you a per-queue process floor (idle workers, and less of the ceiling left for busy queues).
Balancing off gives you a shared pool (no idle floor) and charges you starvation (strict priority order means a flood on one queue stops every queue below it).

Both costs scale with queue count, which is why teams with many queues feel them most. More queues means a taller idle floor under Option A, and under Option B a longer priority list with more queues below any flood. The granularity that made thirty queues attractive makes both options expensive.

Skyline's third option: weight the queues

The dilemma assumes that "balancing off" must mean strict priority: all of high before any of default. Skyline keeps the single shared pool of balance => false, with no per-queue minimum and no idle floor, and replaces strict list order with a proportional one via a queueWeights map:

'supervisor-1' => [
    'connection'   => 'redis',
    'queue'        => ['high', 'default', 'low'],
    'balance'      => false,
    'maxProcesses' => 10,
    'queueWeights' => [
        'high'    => 3,
        'default' => 2,
        // 'low' is omitted, so it gets the default weight of 1
    ],
],

Instead of always checking high first, workers check the queues in proportion to their weights, roughly 3 : 2 : 1. About 50% of pickups favour high, 33% default and 17% low. Queues you leave out of the map get a weight of 1, so a queue you forget to list still gets picked up.

Take the same flood of fifty thousand jobs on high. Under strict priority, low would get no workers until high drained. Under weights, most pickups still go to high, which is weighted highest, but one in six reaches low, so low keeps draining instead of stalling.

How weighted queues compare with both balancing modes

No idle-worker floor. Weights live under balance => false, so there's no per-queue minProcesses. Thirty queues do not mean thirty resident workers. They share one pool, the same as plain unbalanced mode.
No starvation. Every queue has a weight of at least 1, so every queue is checked on a regular cadence. A flood can reduce a sibling queue's share, but not its throughput to zero.
Explicit priority. A 3 : 2 : 1 map says how much each queue matters, instead of encoding priority in list position or paying for it with dedicated worker pools.
Per-queue operations stay. You keep per-queue stats, pause, drain and inspect for all thirty queues without paying the cost of balancing.

When should you still use `balance => 'auto'`?

Weighted queues don't replace balance => 'auto' everywhere. Auto-balancing's strength is elastic capacity: it starts more workers for a queue that is spiking, stops them afterwards, and scales the total process count to demand. Weights don't add processes. They redistribute a fixed pool across queues. If your bottleneck is throughput on one queue and you have CPU headroom, auto-scaling is still the better fit.

Weighting fits a specific, common setup best: many queues kept for operational granularity, most of them idle most of the time, with occasional floods on one queue that should not hold up the others. That is also where the balance on/off choice costs the most.

Extending the Horizon Dashboard: Adding a UI to a Compiled Vue Bundle

laravel-o11y — Sun, 13 Sep 2026 16:39:28 +0000

Horizon's dashboard is a compiled Vue application with no plugin API. If you want to add a panel to the job details page, the usual options are to fork the package or to publish its assets and patch the bundle, and both mean redoing the work on every release. knobik/laravel-horizon-job-output takes a third approach that needs neither.

The package gives a queued job the same output API an Artisan command has ($this->info(), table(), withProgressBar()) and streams that output onto Horizon's job details page while the job runs. It also adds a Reserved Jobs page to the sidebar and a Cancel Batch card to the batch screen. None of this forks Horizon, publishes its assets or modifies Horizon's code.

This article walks through how it does that. The same techniques apply to any package that extends a Laravel package whose frontend ships pre-compiled.

Credit where it is due

Every technique below comes from knobik/laravel-horizon-job-output, by knobik, MIT licensed. The code quoted in this article is theirs, abridged for length. We are writing it up because it solves cleanly a problem most people solve by forking. If any of it is useful to you, star the repo.

Key takeaways

Get your data in through the repository, not a new endpoint. RedisJobRepository::$keys is a public whitelist read with HMGET. Append a field to it and that field flows through Horizon's existing /api/jobs/{id} response with no route or controller override.
Override the layout view, then render the original from a second namespace. addNamespace('horizon-original', …) plus prependNamespace('horizon', …) lets you patch Horizon's real rendered HTML instead of shipping a copy of it that drifts.
Mount inside Vue's in-DOM template, not into Vue-owned DOM. A <div> spliced in after <router-view></router-view> compiles to a static node: Vue renders it once and never patches it again, so your plain JavaScript owns it safely.
Horizon's catch-all route gives you SPA routes for free. It serves the layout for any path under the dashboard prefix, so a URL the compiled router has no route for renders an empty router view, which leaves your mount as the only thing on the page.
Register routes in register(), not boot(). Every provider's register() runs before any provider's boot(), which is the only placement that beats Horizon's catch-all regardless of package discovery order.
Assume every anchor will move. Each patch is independently optional, logs what the dashboard will be missing, and a scheduled CI job runs the suite against laravel/horizon:dev-master so drift arrives as a warning rather than a bug report.

The problem: a dashboard with no seams

Horizon ships its frontend as a compiled bundle in public/vendor/horizon, mounted by a Blade layout that is little more than one <div id="horizon"> containing a <router-view>, a sidebar and a script tag. There is no Horizon::registerPanel(), no view slot and no JavaScript event bus.

That leaves three usual options:

Approach	Cost
Fork Horizon	You now maintain a queue dashboard. Every upstream release is a merge.
Publish and patch the assets	Your patch is a build artifact in `public/`. `horizon:publish` overwrites it on the next deploy without warning.
Ship a copy of the layout view	Works until Horizon changes its layout, at which point your users get the old dashboard with none of the new features and no error to explain it.

The package does none of these. It uses Horizon's rendered HTML as the extension point and treats every assumption about that HTML as provisional: it patches the render output, not the source. The rest of the design follows from that decision.

Getting your data into Horizon's API

The output has to reach the browser first. The obvious way is a new endpoint, GET /horizon/api/job-output/{id}, with your own controller and your own Redis read. The package avoids adding one.

Horizon reads each job out of Redis in RedisJobRepository, and it does not use HGETALL. It reads a fixed whitelist of hash fields with HMGET, and that whitelist is a public property:

// Knobik\HorizonJobOutput\HorizonJobOutputServiceProvider
protected function exposeOutputOnJobRepository(object $repository): void
{
    if (! property_exists($repository, 'keys')) {
        return;
    }

    if (! in_array(JobOutputStore::FIELD, $repository->keys, true)) {
        $repository->keys[] = JobOutputStore::FIELD;
    }
}

The repository is a singleton, so appending output to it once at boot applies process-wide. From then on, Horizon's own /api/jobs/{id} endpoint returns the field alongside status, payload and the rest. The dashboard makes no second request, and there is no new route or controller whose authorization could be wrong: the data comes back from an endpoint Horizon already gates.

Storage follows the same approach. The output is written as a field on Horizon's own job hash rather than under a key of its own:

// Knobik\HorizonJobOutput\RedisJobOutputStore
public function put(string $jobId, string $output): bool
{
    $connection = $this->connection();

    if (! $connection->exists($jobId)) {
        return false;
    }

    $connection->hset($jobId, self::FIELD, $output);

    return true;
}

Sharing the key means sharing its TTL. Horizon already trims completed, failed and recent jobs on the schedule set by horizon.trim.*, and because the output is a field on that same hash, the same policy trims it. There is no cleanup command to run and no way for the two lifetimes to drift apart; a separate key would have needed a retention policy of its own. The exists() guard is what keeps this safe: HSET on a missing key would create a new hash with no expiry, a leak that grows by one key per job and never shrinks.

Owning the layout without forking it

Laravel's view finder resolves horizon::layout through a namespace hint. A package that registers its own view directory under the horizon namespace with prependNamespace() wins that lookup. That part is well known. The problem is that you then have to supply a layout, which usually means copying Horizon's and keeping the copy in sync with every release.

The package avoids that by keeping Horizon's own view path reachable under a second name before taking over the first:

// Knobik\HorizonJobOutput\HorizonJobOutputServiceProvider
protected function registerViewOverride($view): void
{
    $finder = $view->getFinder();
    $hints = $finder->getHints();

    if (! isset($hints['horizon'])) {
        return;
    }

    $finder->addNamespace('horizon-original', $hints['horizon']);
    $finder->prependNamespace('horizon', __DIR__.'/../resources/views');
}

The override view is then three lines, none of them Horizon's markup:

{!! app(\Knobik\HorizonJobOutput\LayoutDecorator::class)->decorate(
    view('horizon-original::layout', ['isDownForMaintenance' => $isDownForMaintenance])->render()
) !!}

Horizon renders its real layout, and the decorator receives the resulting HTML string and splices things into it. A Horizon release that changes the sidebar, the theme switcher or the asset URLs changes them here too, because this is Horizon's layout with a few extra nodes added.

Two more details are worth copying. The registration runs from $this->app->booted() and through callAfterResolving('view', …), so a request that never renders a view never pays to construct Blade's finder. And every splice goes through one method, which logs a missing anchor and returns the HTML unchanged:

// Knobik\HorizonJobOutput\LayoutDecorator
protected function patch(string $html, string $anchor, string $insert, string $missing, bool $before = false, int $from = 0): string
{
    $position = strpos($html, $anchor, $from);

    if ($position === false) {
        $this->warn($anchor, $missing);   // logs what the dashboard will be missing

        return $html;
    }

    return substr_replace($html, $insert, $before ? $position : $position + strlen($anchor), 0);
}

Each caller passes its own $missing string, such as "the output panel will not be shown", "the Reserved Jobs link will be missing" or "nothing this package adds will load". If a Horizon release moves an anchor, the result is a log line naming the feature that disappeared, rather than a 500 on the dashboard or a blank panel with nothing in the logs.

Where to put a mount point in a Vue app you don't control

The usual approach is to wait for the SPA to render and then appendChild into it. That puts your node inside DOM that Vue's virtual DOM believes it owns, and the next patch (a poll updating the job status, or a route change) either removes it or leaves Vue diffing against a tree that no longer matches.

The package inserts its mounts server-side, into the HTML string, immediately after Horizon's router view:

protected const ROUTER_VIEW_ANCHOR = '<router-view></router-view>';

// ...

return $this->patch($html, self::ROUTER_VIEW_ANCHOR, $mounts, 'the output panel will not be shown');

That position puts the <div id="hjo-root"> inside #horizon, which Vue uses as its in-DOM template. Vue compiles the element's existing markup into its render function, and a node with no directives, bindings or interpolation compiles to a static node: rendered once, then skipped by every later patch. So the mount sits inside the app, at the right place in the layout, and the diff never touches it. Plain JavaScript can own it.

The scripts and styles go just before </body>, outside #horizon, so Vue never tries to compile them.

The general rule

If you need to add DOM to a compiled SPA you don't control, add it to the template the app compiles from, before the app boots, and not to the DOM the app has already rendered. Markup in the template becomes a static node the framework leaves alone. A node appended to rendered DOM can be removed by the next re-render.

Adding a whole page the compiled router has never heard of

The package also adds a new page, Reserved Jobs at /horizon/reserved, to a compiled router that has no route for it.

This works because Horizon's dashboard routes end in a catch-all GET route that matches every path under the prefix and returns the same layout. So /horizon/reserved already serves the app. The compiled Vue router finds no route matching that path and renders an empty <router-view>, which leaves the package's own mount, placed immediately after it, as the only content in the column.

The sidebar link differs from Horizon's own nav markup in one way:

<li class="nav-item">
    <a href="{$href}" class="nav-link d-flex align-items-center" data-hjo-nav>
        <svg …></svg>
        <span>Reserved Jobs</span>
    </a>
</li>

It is a plain <a href>, not a <router-link>. The nav is inside #horizon, so Vue compiles whatever is put there, and a router-link pointing at a route the bundle does not know about resolves to nothing. A plain href performs a full navigation, and Vue leaves it alone. The href is built from horizon.proxy_path and horizon.path, mirroring how Horizon's own bundle computes its base path, so the link still works with a custom dashboard path or behind a reverse proxy.

Registering routes Horizon's catch-all won't swallow

The Reserved Jobs page needs an API endpoint, and that endpoint lives under the same prefix as the catch-all. When two routes match, the one registered first wins.

Horizon adds its catch-all from boot(), so the package registers its routes from register():

public function register(): void
{
    $this->mergeConfigFrom(__DIR__.'/../config/horizon-job-output.php', 'horizon-job-output');

    // ... bindings ...

    // Registered here rather than in boot(). Horizon's dashboard ends in a
    // catch-all route matching everything under its prefix, added from its
    // own boot(), and whichever route is registered first wins. Every
    // provider's register() runs before any provider's boot(), so this is
    // the only placement that beats the catch-all no matter what order the
    // packages were discovered in.
    $this->registerRoutes();
}

You don't control package discovery order, but the container guarantees that every register() runs before any boot(), so a route registered in register() always comes first.

The cost is that Horizon has not booted yet, so its route group cannot be reused and has to be rebuilt, middleware stack included:

protected function middleware(): array
{
    $middleware = (array) config('horizon.middleware', ['web']);

    if (class_exists(SentinelMiddleware::class)) {
        array_unshift($middleware, SentinelMiddleware::class.':horizon');
    }

    return $middleware;
}

Newer Horizon versions collect this into a named horizon middleware group, but that group does not exist across the whole ^5.0 range the package supports, and naming a group that was never registered makes the router try to resolve a class by that name. Rebuilding the list works on every version in the range.

Authorization needs more care. Horizon attaches its Authenticate middleware in its base controller, not on the route group, so a controller that does not extend that base class gets no authorization check. The package applies the middleware explicitly, around the whole route file rather than per route:

// routes/reserved-jobs.php
Route::middleware(Authenticate::class)->group(function () {
    Route::get('/api/reserved-jobs', [ReservedJobsController::class, 'index']);
    Route::post('/api/reserved-jobs/release', [ReservedJobsController::class, 'release']);
});

If you are writing your own Horizon extension, check where the package you are extending applies its gate. A route group under horizon.middleware alone gets you the web stack and nothing else, so your endpoint would be open to anyone who can reach the dashboard's URL, whether or not they pass the viewHorizon gate.

The feature toggles are enforced in the controllers, not around route registration:

public function index(): array
{
    abort_unless(config('horizon-job-output.reserved_page', true), 404);

    return ['jobs' => $this->reserved->all()->all()];
}

Gating the registration would bake the setting into a cached route table, so changing the config would have no effect until someone ran route:clear. Checking in the controller avoids that.

Reacting to navigation without access to the router

The panel has to know when the user navigates to a job details page. It cannot ask the router, because the router is inside a bundle the package has no reference to. Vue Router in history mode pushes state rather than reloading, so the package wraps the two history methods it calls and re-announces them as an ordinary DOM event:

['pushState', 'replaceState'].forEach((method) => {
    const original = history[method];

    history[method] = function () {
        const result = original.apply(this, arguments);
        window.dispatchEvent(new Event('hjo:navigated'));
        return result;
    };
});

function onNavigation(sync) {
    window.addEventListener('hjo:navigated', sync);
    window.addEventListener('popstate', sync);

    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', sync);
    } else {
        sync();
    }
}

The browser fires popstate for the back and forward buttons; the wrapper covers navigation the app triggers itself, which does not fire it. This code lives in a shared support module concatenated ahead of the feature scripts, so the history methods are wrapped once however many features are enabled, instead of by whichever feature script happened to load first.

The current screen is then read from the URL, since every Horizon screen has its own path:

function currentJobId() {
    const path = support.dashboardPath();

    const preview = path.match(/^\/jobs\/[^/]+\/([^/]+)\/?$/);
    if (preview) {
        return preview[1];
    }

    const failed = path.match(/^\/failed\/([^/]+)\/?$/);
    if (failed) {
        return failed[1];
    }

    return null;
}

Because Vue creates the mount point when it compiles the layout template, on a cold load this code can run before the element exists. whenElementExists retries up to 50 times at 100ms intervals instead of assuming a boot order.

Shipping frontend assets with no build step

A package extending a compiled dashboard cannot add itself to that dashboard's build. Publishing files into public/ works, but it needs a publish step in every deploy, and Horizon's own horizon:publish writes to the same directory.

So everything is inlined into the layout at render time: one <style>, one <script type="module">, and a settings object serialised with Js::from(). That is the same helper Horizon uses for its own settings, and it applies the escaping needed to embed data inside a script tag.

The terminal renderer takes more work. The package vendors an xterm.js build so a progress bar redraws in place on the dashboard as it would in a shell. An ESM build ends in an export statement, and nothing can import from an inline module, so the export does nothing there. The package rewrites it into a global assignment as it inlines the file:

protected const EXPORT_PATTERN = '/export\s*\{\s*(\w+)\s+as\s+Terminal\s*\}\s*;?/';

// The export is the last statement in the bundle, so only the tail is
// searched. Running the pattern over the whole 345KB build would repeat
// that scan on every dashboard request for no added certainty.
$tail = substr($js, -self::TAIL_BYTES);

if (! preg_match(self::EXPORT_PATTERN, $tail, $matches, PREG_OFFSET_CAPTURE)) {
    Log::warning('[horizon-job-output] Could not rewrite the xterm export, so the terminal renderer was skipped. …');

    return ['css' => '', 'js' => ''];
}

$js = substr_replace($js, 'globalThis.HorizonJobOutputTerminal = '.$matches[1][0].';', /* … */);

Rewriting a vendored bundle with a regular expression is brittle, and the package handles it accordingly. The pattern runs over the last 512 bytes only, a miss is logged, and the panel falls back to an HTML renderer that collapses the control sequences and needs no extra payload. A failed rewrite costs you the xterm renderer, not the output panel.

Capturing output from a job that is already running

The dashboard side needs output to show, and getting an output object into a running job has problems of its own.

It cannot happen at dispatch. A queued job is serialised, and an unserialised object never runs its constructor, so anything the constructor attached is gone by the time the worker has it. The attachment has to happen at execution time, inside the worker, which is what a global bus pipe allows:

protected function registerBusPipe(): void
{
    $dispatcher = $this->app->make(BusDispatcherContract::class);

    if (! $dispatcher instanceof BusDispatcher) {
        return;
    }

    try {
        $property = new ReflectionProperty($dispatcher, 'pipes');
        $pipes = (array) $property->getValue($dispatcher);
    } catch (Throwable) {
        $pipes = [];
    }

    if (in_array(CaptureJobOutput::class, $pipes, true)) {
        return;
    }

    $pipes[] = CaptureJobOutput::class;

    $dispatcher->pipeThrough($pipes);
}

pipeThrough() replaces the pipe list outright and there is no getter, so the package reads the existing pipes by reflection and appends to them. Replacing the list instead would drop the pipes other packages have registered, with no error.

Two cases need their own handling:

Artisan commands run inside a job. The console kernel writes a command's output to whatever buffer it is handed and discards it when handed nothing. So the kernel is decorated for the length of the job (its call() supplies the job's output as the default buffer) and restored in a finally, because a worker handles one job after another in the same process and a stale decorator would feed a finished job's output. The facade's resolved instance is cleared alongside the binding, since Artisan::call() is how a job runs a command in practice and a facade holds on to whatever it resolved first.
Queued Artisan commands. Artisan::queue() dispatches a QueuedCommand, which does not use InteractsWithQueue, so nothing ever sets a job on it and the bus pipe has no way to reach the Horizon id its output belongs on. The package listens to Queue::before() / after(), keeps the job the worker has in hand in a small singleton, and only hands out its id when the payload's commandName matches the command being piped. That check stops a command dispatched inside another job from writing over the outer job's output.

The write path is buffered with a flush interval, capped at max_bytes, and flushed with force: true from a finally. A job that throws keeps whatever it wrote before the exception, which is usually the output you most want to read.

Designing for the day Horizon changes

Everything above depends on internals that carry no compatibility guarantee: a public property on a repository, a private property read by reflection, two string anchors in rendered markup, and the shape of a trailing export in a vendored bundle. Any Horizon release could break one of them, so the package is built to make that breakage cheap and visible.

Every patch is independently optional: a missing anchor costs you that one feature and logs which one. Every failure is a Log::warning naming the anchor and the consequence, so the first person to hit it can diagnose it without reading the package source. And a scheduled CI job tests against Horizon's development branch:

# .github/workflows/horizon-canary.yml
on:
  schedule:
    - cron: '41 6 * * 1'

# ...

      - name: Install Horizon from its development branch
        run: |
          composer require --no-update "laravel/horizon:dev-master"
          composer update --no-interaction --prefer-dist

It runs the full suite against laravel/horizon:dev-master once a week and, on failure, opens a labelled issue listing which four internals might have moved. Upstream drift shows up as an issue on a Monday morning, not as a user's bug report after a release.

The pattern, generalised

The same mechanisms work for extending any Laravel package that ships a compiled frontend:

You want to…	Mechanism	What it depends on
Add a field to an existing API response	Mutate the repository's field whitelist at boot	The property staying public
Add markup to a view you don't own	Re-register the original under a second namespace, prepend your own, render and patch	String anchors in the rendered HTML
Own DOM inside a compiled SPA	Splice a bare element into the in-DOM template server-side; it compiles to a static node	The framework not patching static nodes
Add a page to a compiled router	Use the host's catch-all route; render into your own mount when the router matches nothing	A catch-all existing at all
Beat a catch-all route	Register from `register()`, not `boot()`	Nothing; the container guarantees the order
Observe SPA navigation	Wrap `history.pushState`/`replaceState`, re-dispatch as an event, plus `popstate`	History-mode routing
Attach state to a running job	A global bus pipe, appended to the existing pipes reflectively	`Dispatcher::$pipes` staying where it is

Apart from the route ordering, none of these dependencies is guaranteed. The approach holds up because each assumption is isolated to one feature, degrades to that feature missing plus a log line saying so, and is checked by CI against the upstream development branch.

The source is around 1,500 lines of PHP and JavaScript, and close to half of it is comments explaining why the code is written the way it is.

Laravel Background Jobs: 12 Best Practices for Production Queues

laravel-o11y — Wed, 26 Aug 2026 16:18:00 +0000

Queued jobs are the part of a Laravel app that runs when you're not looking — after the request is gone, during a deploy, against data that may have changed or vanished, on code one version newer than the code that dispatched them. Most job bugs aren't logic errors; they're assumptions about when and how many times a job runs that quietly hold in development and fall apart under production load.

Here are twelve practices that keep a queue healthy under real traffic. They build on each other: small arguments make idempotency easier, idempotency makes retries safe, safe retries make backoff useful, and so on. The last one — backwards compatibility across deploys — is the one that bites hardest and no linter catches.

Key takeaways

Assume every job runs at least twice. Laravel's queues are at-least-once, and a worker killed mid-job re-runs it from scratch — with the side effects of the first attempt still committed.
Keep jobs small, atomic and explicitly queued. One job per record beats one job that loops over 10,000: a failure then retries one unit of work instead of everything.
Let the framework handle failure. Declarative $tries and exponential backoff() rather than manual re-runs, and afterCommit() so a worker can't outrun your transaction.
Read the whole contract before using ShouldBeUnique or batches. Both fail silently — a missing uniqueId() drops jobs with no error anywhere.
The queue outlives your deploy. Jobs serialized against old code are deserialized by new workers, so renaming a job class or adding a constructor argument without a class-level default destroys work that is already in flight.

1. Keep arguments small

Every byte of constructor arguments is a byte in Redis, multiplied by every queued instance. Don't pass big arrays, blobs, or rich DTOs "to save a query." Pass the minimal identifiers and re-read what you need inside handle(). A queue backlog of fat jobs is how you OOM Redis.

If you pass Eloquent models, Laravel can serialize just the class and the ID and automatically re-reload the record on execution — as long as you include the SerializesModels trait.

2. Every job should declare its queue

class GenerateImageThumbnails implements ShouldQueue
{
    public $queue = 'media';
}

Horizon routes work by queue name, and each supervisor is tuned for a workload — concurrency, timeout, balance strategy. A job with no $queue lands on default, where a slow image resize sits behind — or ahead of — a latency-sensitive job.

Mixing fast and slow, or urgent and bulk, on one queue defeats the entire point of having supervisors.

Pick the queue that matches the work's shape and SLA, and make sure a matching Horizon supervisor processes it.

3. Make jobs idempotent

Horizon delivers at-least-once. A worker that's killed mid-job — deploy, OOM, timeout — leaves the job to be retried, so the same job body can run twice. Design every job so that running it twice produces the same end state as running it once:

Check before you create (firstOrCreate, updateOrCreate, "already sent?" guards).
Use unique constraints as a backstop, not wishful thinking.
Never assume "this ran, therefore it ran exactly once."

The realistic failure mode isn't a clean re-run from the top — it's a job that did partial work and then got killed before completing. Redis only removes a job from its reserved set on success, so a hard kill (SIGKILL from a per-job timeout, or the supervisor force-killing a worker that outlived the shutdown grace window during a deploy) leaves the job to be migrated back and re-run from scratch — with whatever side effects the first attempt already committed still in place.

Because attempts is incremented when the job is reserved, not when it fails, each kill-and-recover cycle burns one try; after maxTries such cycles the job is marked failed having run its side effects several times with no clean completion. So idempotency has to cover resuming after a partial run, not just "don't duplicate a fully-successful run."

4. Keep jobs atomic and short

A deploy restarts workers; a job that exceeds its $timeout is killed mid-flight. If your job does five writes and dies after three, the retry redoes all five — and the first three had better be idempotent (see above).

Prefer one job per record over one job that loops 10,000 records. A per-record job that dies retries one record; a mega-job retries everything and may never finish inside the timeout window. Fan out:

Item::where(...)->eachById(fn (Item $i) => SyncItemJob::dispatch($i));

5. Retries and backoff — let the framework do it

Don't manually re-run failed jobs and don't catch-and-swallow. Configure retries declaratively:

public $tries = 5;

// exponential backoff — required for anything hitting an external API
public function backoff(): array
{
    return [10, 30, 60, 300];
}

Hammering an API with immediate retries turns a transient blip into an outage. Back off. Let jobs that genuinely can't succeed land in failed_jobs — that's a signal to fix the root cause, not a thing to mass-retry. Use $this->fail($e) to bail early when you know a retry won't help.

6. Dispatch after the transaction commits

DB::transaction(function () {
    $booking = Booking::create([...]);
    SendBookingConfirmation::dispatch($booking->id)->afterCommit();
});

Without afterCommit() (or the connection-level 'after_commit' => true), a fast worker can pick up the job and find() a booking that hasn't been committed yet — ModelNotFoundException, a spurious failure that only reproduces under load. Dispatch the side effect only once the data it depends on is durable.

7. The `ShouldBeUnique` contract — three ways to get it wrong

Unique jobs are where the most expensive, silent bugs live. This section is the short version; the long one — including how uniqueness interacts with WithoutOverlapping, retries and orphaned locks — is in Laravel job uniqueness controls.

Set uniqueFor. A plain ShouldBeUnique lock is acquired at dispatch and released only when processing reaches a terminal state (success, or final failure after maxTries) — it is held across the whole processing window and across backoff retries. Without uniqueFor the lock is created with no TTL (forever()), so it is reclaimed only by that eventual terminal run. Normally that's fine: a worker killed mid-job leaves the job to be retried, and the retry's terminal state clears the lock. The exposure is twofold:

Until that retry completes, every new dispatch of the same unique job is silently dropped — not errored, just gone. uniqueFor bounds this window to a known TTL instead of "however long the kill→retry→finish cycle takes."
If the job never reaches a terminal run — a uniqueId() that reads external mutable state (so the release computes a different key than acquire), a lost reserved entry, or maxTries: 0 with a job that's killed every attempt — the forever() lock is never reclaimed and the job is silently undispatchable until the key is cleared by hand. uniqueFor is the only thing that auto-recovers it.

Caveat: uniqueFor must exceed your worst-case total processing-plus-retry time, or the lock expires mid-legitimate-run and a duplicate can be dispatched. It's a ceiling on the deadlock risk, not a free safety net — keep uniqueId() a pure function of the job's own data.

public int $uniqueFor = 3600; // lock self-heals after an hour

uniqueId is mandatory for parameterized jobs. The lock key is laravel_unique_job:<class>:<uniqueId>. Omit uniqueId on a job that takes arguments and the key collapses to the class name alone — so SyncCompany(1) and SyncCompany(2) share one lock and one of them is silently dropped at dispatch. Lost work, no error.

public function uniqueId(): string
{
    return (string) $this->companyId;
}

A genuinely class-wide singleton is fine — make the intent explicit by returning a constant from uniqueId().

8. Never bulk or batch a unique job

Queue::bulk() / Bus::bulk() push raw payloads straight to Redis, skipping the dispatcher that acquires the lock — uniqueness silently does nothing. And batching a unique job means a dropped duplicate desyncs the batch's up-front job count, so its then/finally callbacks never fire and the batch hangs as "pending" forever. Dispatch unique jobs individually.

Periodic / scheduled jobs should implement ShouldBeUnique so a slow run doesn't overlap the next tick.

9. A batchable job must honour cancellation

Cancelling a batch only stops future dispatches — jobs already on the queue still wake up and run their full body unless they check. For anything that mutates state (writes files, calls APIs, charges cards), that's wasted work against a batch the caller abandoned. Guard it:

public function handle(): void
{
    if ($this->batch()?->cancelled()) {
        return;
    }
    // ... heavy work
}

…or centralise it with the Illuminate\Queue\Middleware\SkipIfBatchCancelled middleware.

10. Don't `sleep()` in a job

A sleeping job pins a worker doing nothing, starving every other job behind it. If you need to wait — rate limits, a not-yet-ready upstream — release the job back with a delay instead:

$this->release(60); // re-queue, free the worker, try again in a minute

11. The queue outlives your deploy — backwards compatibility

This is the one that bites hardest and isn't covered by any linter, so read it twice.

When you deploy, there are already jobs sitting in the queue, serialized against the old code. A worker on the new code has to deserialize and run them. Two ways this goes wrong.

Renaming or moving a job class

The serialized payload stores the fully-qualified class name — App\Products\Jobs\SyncStockJob. Rename the class, move it to another namespace, or delete it, and every already-queued instance becomes unresolvable: deserialization throws, the job lands in failed_jobs, the work is lost.

So:

Two-phase it. Keep the old class (even as a thin subclass of the new one) for one deploy cycle, let the queue drain, then remove it in a follow-up deploy.
Or drain the queue of that job type before shipping the rename.
Don't rename a hot job class in the same PR that renames its behaviour.

Changing constructor arguments

The subtle one. PHP's unserialize() does not call the constructor — it restores the saved properties directly. So your constructor's default values do nothing for jobs already in the queue.

class SyncStockJob implements ShouldQueue
{
    // ⚠️ promoted, no class-level default.
    // An old payload serialized before $force existed restores WITHOUT it →
    // accessing $this->force throws "must not be accessed before initialization".
    public function __construct(
        public int $productId,
        public bool $force = false,
    ) {}
}

The constructor default = false only helps new dispatches. An old queued job never goes through the constructor, so its $force stays uninitialized, and the new handle() that reads it crashes. Fix: give the property a class-level default so deserialized old jobs fall back gracefully:

class SyncStockJob implements ShouldQueue
{
    public bool $force = false; // ← real default, survives unserialize

    public function __construct(public int $productId, bool $force = false)
    {
        $this->force = $force;
    }
}

Which job changes are safe to deploy?

The question to ask of any change is: what happens to a payload that was serialized an hour ago, by the code you are about to replace?

Change	Safe in one deploy?	What happens / what to do
Edit `handle()` body	Yes	Behaviour isn't serialized — only properties are. Just make sure it tolerates the old payload shape.
Add a property with a class-level default	Yes	Old payloads restore without the key and fall back to the default.
Add a promoted constructor argument	No	`unserialize()` never calls the constructor, so the property stays uninitialized and reading it throws. Give it a class-level default instead.
Remove or rename a property	No	In-flight payloads still carry the old key. Deprecate over one deploy cycle, then remove.
Rename / move / delete the job class	No	The FQCN is stored in the payload; queued jobs become unresolvable and land in `failed_jobs`. Two-phase it, or drain first.
Change the queue name	Yes, with care	Jobs already queued stay on the old queue — keep a supervisor processing it until it drains.

The general rules that fall out of that:

New properties get a class-level default value (or are nullable), never a bare typed property.
Don't remove or rename a property a queued payload still carries without a deprecation window.
handle() must tolerate both the old and the new payload shape for the length of one deploy cycle.
When in doubt, two-phase: ship the backwards-compatible change, let the old jobs drain, clean up in a later deploy.

12. Watch it run

Use Horizon. Watch queue wait times, failure rates, and throughput per queue — a backlog on one supervisor is invisible from the others. A job that's "working" in the sense of not erroring can still be silently 20 minutes behind. Instrumentation is how you find out before a customer does.

The core takeaway

Write every job assuming it will run twice, run late, run against a deleted record, and run on code that's one version newer than the code that dispatched it. Idempotency, atomicity, backoff, afterCommit, an explicit queue, the full ShouldBeUnique / batch contracts, and — above all — backwards compatibility across deploys.

DEV Community: laravel-o11y

Laravel Job timeout vs retry_after: The Ordering Rule Nothing Enforces

Key takeaways

The two numbers and their defaults

What retry_after does

What timeout does

Why the two collide, and why equal values fail

The two symptoms, and which one you get

With tries => 1: a failure on work that succeeded

With tries => 2 or more: concurrent execution with no error

Four ways a correct config becomes an incorrect one

The ordering rule, with numbers

Catching it in the logs

Further reading

Common questions

What is retry_after in Laravel queues?

What are the default values of timeout and retry_after?

Why is my Laravel job running twice?

Is it safe to set timeout equal to retry_after?

Why did my job fail with MaxAttemptsExceededException when it actually succeeded?

Laravel Horizon Queue Balancing: Idle Workers vs. Starved Queues

Key takeaways

Why you end up with thirty queues in the first place

Option A: balance => 'auto' and the idle-worker floor

Option B: balance => false and starvation by list order

What is the difference between balance auto, simple and false?

Why the trade-off gets worse with every queue you add

Skyline's third option: weight the queues

How weighted queues compare with both balancing modes

When should you still use balance => 'auto'?

Extending the Horizon Dashboard: Adding a UI to a Compiled Vue Bundle

Key takeaways

The problem: a dashboard with no seams

Getting your data into Horizon's API

Owning the layout without forking it

Where to put a mount point in a Vue app you don't control

Adding a whole page the compiled router has never heard of

Registering routes Horizon's catch-all won't swallow

Reacting to navigation without access to the router

Shipping frontend assets with no build step

Capturing output from a job that is already running

Designing for the day Horizon changes

The pattern, generalised

Laravel Background Jobs: 12 Best Practices for Production Queues

Key takeaways

1. Keep arguments small

2. Every job should declare its queue

3. Make jobs idempotent

4. Keep jobs atomic and short

5. Retries and backoff — let the framework do it

6. Dispatch after the transaction commits

7. The ShouldBeUnique contract — three ways to get it wrong

8. Never bulk or batch a unique job

9. A batchable job must honour cancellation

10. Don't sleep() in a job

11. The queue outlives your deploy — backwards compatibility

Renaming or moving a job class

Changing constructor arguments

Which job changes are safe to deploy?

12. Watch it run

The core takeaway

What `retry_after` does

What `timeout` does

With `tries => 1`: a failure on work that succeeded

With `tries => 2` or more: concurrent execution with no error

Option A: `balance => 'auto'` and the idle-worker floor

Option B: `balance => false` and starvation by list order

What is the difference between `balance` auto, simple and false?

When should you still use `balance => 'auto'`?

7. The `ShouldBeUnique` contract — three ways to get it wrong

10. Don't `sleep()` in a job