Skip to content

Document the queue worker job timeout for workflow tasks - #578

Merged
rmcdaniel merged 8 commits into
mainfrom
docs/1231-worker-timeout
Nov 20, 2026
Merged

rmcdaniel merged 8 commits into
mainfrom
docs/1231-worker-timeout

Conversation

@rmcdaniel

@rmcdaniel rmcdaniel commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Documents the queue worker job timeout for workflow tasks (durable-workflow/workflow#1231, durable-workflow/workflow#1244).

With the pcntl extension, queue:work kills a job after --timeout seconds, which defaults to 60. A workflow task killed that way is rolled back and retried after its lease expires. A workflow task that always needs longer, such as one scheduling or finishing a wide all(), never completes.

  • installation.md gets a new Worker timeout section ({#worker-timeout}) under Running Workers. A killed workflow task is retried only after its lease expires and is counted as a lost lease. The workers serving workflow tasks need a timeout that covers the longest workflow task, with retry_after above it, while activities keep a bounded timeout on their own queue: the example sets the activity class's $queue so the bounded worker actually receives activities. Horizon's timeout is the same setting. It describes the opt-in DW_V2_WORKFLOW_TASK_JOB_TIMEOUT_SECONDS and the worker-start warning added in Workflow 2.34.0.
  • Every page that starts a workflow worker links to that section: quickstart.md, sample-app.md, laravel-adoption.md (embedded v2 worker) and configuration/microservices.md. ensuring-same-server.md only starts activity workers and is unchanged.
  • All seven locales (de, es, fr, ja, pt-BR, uk, zh-Hans) are translated, and source-hashes.json is updated. check-doc-translations.js passes with DOCS_TRANSLATION_BASE set to the main commit, as does check-doc-translation-updates.test.js.

🤖 Generated with Claude Code

rmcdaniel and others added 2 commits November 19, 2026 16:19
With pcntl, queue:work kills a job after --timeout seconds (60 by default). A
workflow task killed that way is rolled back and retried after its lease
expires, so a task that always needs longer never completes
(durable-workflow/workflow#1231). Document running workflow workers with
--timeout=0 or above the longest workflow task in Running Workers, and link it
from every page that starts a workflow worker.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Mirror the English Worker timeout subsection in Installation and the links to
it from the quickstart, sample app, Laravel adoption and microservices guides
into de, es, fr, ja, pt-BR, uk and zh-Hans, keeping the {#worker-timeout}
anchor, commands and config keys unchanged. Record the reviewed English source
hashes for the five guides in each locale's source-hashes.json.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
rmcdaniel and others added 6 commits November 19, 2026 18:08
A blanket --timeout=0 lets a hung activity hold its worker forever and breaks
Laravel's rule that retry_after exceeds every job's timeout. Explain how the
workflow task timeout, the task lease and retry_after relate, and recommend a
dedicated workflow-task connection (retry_after above the lease, workers with
--timeout below it) with activities on a bounded queue. Note that newer
releases give workflow task jobs this timeout themselves.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Replace the Worker timeout subsection of Installation in de, es, fr, ja,
pt-BR, uk and zh-Hans with a translation of the rewritten English section:
how the workflow task timeout, the task lease and retry_after relate, the
dedicated workflow-task connection, and the newer-release behaviour. Code
blocks and the {#worker-timeout} anchor are unchanged. Record the reviewed
English installation.md hash in each locale's source-hashes.json.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The workflow task job timeout is opt-in from Workflow 2.34.0; by default
the worker's --timeout applies. Drop the claim that work past the lease
cannot complete, say that killed tasks are counted as lost leases, and
route activities to the bounded worker through the activity's $queue.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@sonarqubecloud

Copy link
Copy Markdown

@rmcdaniel
rmcdaniel merged commit 1363e9f into main Nov 20, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent:general Pull request opened by General agent

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant