Timeouts

timeout bounds a single execution attempt, in seconds. It defaults to 300 for every task, and the queue-wide default is configurable:

queue = Queue(default_timeout=120)          # queue-wide default

@queue.task(timeout=30)                     # per task
def scrape(url: str) -> str: ...

scrape.apply_async(args=(url,), timeout=10) # per job

The narrowest setting wins: per-job over per-task over queue default.

What a timeout does

How the deadline is enforced depends on the pool:

This is a property of Python, not a gap: there is no safe way to interrupt an arbitrary thread mid-call. On the thread pool a hard timeout is therefore a bookkeeping outcome — the job is failed and retried on schedule while the orphaned attempt still holds its worker slot until it finishes on its own. Use soft_timeout (below) if you need the task itself to stop, or pool="prefork" if you need the runtime to guarantee it.

A timed-out attempt is a failure, not a cancellation. It consumes one retry; if the budget still has room the job is re-enqueued with the usual backoff, and when the budget is exhausted the job moves to the dead-letter queue.

That means a task with max_retries=3 and timeout=30 can occupy a worker for roughly two minutes across attempts before it dead-letters. Size the two together rather than each on its own.

Soft timeouts

A hard timeout settles the job at the deadline, but on the thread pool it does not stop the work. soft_timeout is the deadline the task polls itself, so the task actually unwinds:

from flexiq import current_job

@queue.task(soft_timeout=25, timeout=30)
def export(dataset: str) -> str:
    rows = []
    for chunk in chunks(dataset):
        current_job.check_timeout()     # raises SoftTimeoutError past 25s
        rows.extend(process(chunk))
    return write(rows)

check_timeout() raises SoftTimeoutError once the soft deadline has elapsed. Because it is an ordinary exception, try/finally still runs and the task can flush partial work, release a lock, or record where it got to.

Set soft_timeout a few seconds below timeout, so the polled deadline is reached before the hard one:

Choosing a value

Set a timeout on every production task. Without one a wedged task holds a worker slot until the process is restarted, and no amount of retry configuration recovers that slot.

• Time the task's realistic worst case, then add headroom — a timeout that trips on ordinary slow days turns into a retry storm.
• Give tasks with an external dependency a timeout shorter than the dependency's own, so you fail on your terms rather than waiting on theirs.
• Split work that cannot fit a sane bound. A job that legitimately needs an hour is usually several jobs, or a workflow.

Related deadlines

expires is the one most often confused with timeout: it bounds staleness in the queue, not runtime. See Enqueue options.