Known limits
These are the limits of this release that you should plan around. Most are by design. Some will change in a later release.
Delivery
- At least once, never exactly once. A job can run again after a crash, a lost lease or a release on shutdown. Use
job.idempotencyKeyfor side effects. - A
retrying,completedorfailedevent can go missing. When an attempt's finishing write lands but its answer is lost, and the job moves on before the worker repeats the write, the worker reports the outcome as unconfirmed and emits no event. The stored job is still correct.
Runtime and stores
- Node.js 22 or newer only. Bun and Deno are not supported or tested yet; support is planned for a later release.
UnsupportedRuntimeErroris thrown only on a runtime with no Node-styleprocess.versions.node. - The only store that ships is in memory.
MemoryStorekeeps jobs in the process, so they are lost when it exits, and other processes cannot see them. To share jobs across pods, use a store adapter that implements the store contract. See Writing your own store. - The store contract is experimental until 1.1. It may change in a minor release before then. See Contract version.
MemoryStoretime never goes backwards. When the system clock steps back, store time stands still until the clock catches up. For the length of the step, delays, leases and schedules run late. Other stores follow their own clock.
Pods and upkeep
- Upkeep runs on worker pods. Recovering expired leases and trimming finished jobs need a pod with a worker. Alerts need a pod with a worker or with
alertsset. A fleet of producers alone sweeps, trims and alerts nothing. - Some health numbers are per pod. The
DEAD_LETTERS_HIGHcount comes from this pod's last sweeper or alert tick. Alerts and the failure-rate window count only this pod's jobs. - Only adjacent releases share a store safely. That is the same major version, with minor versions at most one apart. Others emit
versionSkew, which only warns. See Upgrade notes. - SureQ cannot see a blocked event loop. When the loop is blocked,
health()does not run at all. Your probe's timeout is what detects it. - The default shutdown leaves little room in Kubernetes' default grace period.
close()can take 25 s plus 2 s plus about 1 s, and Kubernetes kills a pod after 30 s by default. ApreStophook or a longershutdownTimeoutcan push it over: then raise the grace period. See Graceful shutdown. - Job names are freed when a worker's close begins. You can start a new worker for the same names while the old one is still draining.
Payloads and logging
maxPayloadBytesandmaxResultBytesdefault to 1 MiB, counted as UTF-8 bytes of the JSON.- SureQ writes no log line per job. Use the job events for job logs.
- Backoff strategy and
retryIffailures log aterror. A strategy orretryIfthat throws or returns a bad value is reported as anerrorevent and logged aterror, notwarn. The job is still retried; a broken strategy falls back to the default backoff. factoron afixedbackoff is ignored, with no warning.
Retention
See Queue options: retention for the policies these refer to.
- A job's own age
keepdoes not exempt it from the queue's orbyNamecount. Jobs kept for none that are still insideresultGracetake count slots too. - A job the sweeper fails, that is not a dead letter, gets the queue's
failedpolicy only.byNameand the job's ownkeepdo not apply. - With
cancelled: 0andresultGrace: 0, cancelling a running job deletes it at once. A worker on another pod then sees its lease lost (leaseLost), not a cancel. - Adding an age to a state that had a count-only or keep-forever policy also ages the jobs already finished under it, from their
finishedAt. - Counts are approximate, by up to
pageSize.