Handling errors
Errors reach you in three ways: thrown from a call such as add, reported as an error event, or stored on a job that failed. Every SureQ error has a stable code, so check the code or use instanceof, never the message.
This page shows one of each: a rejected add, an unknown id, a failed job, and a listener that throws.
Example
import { isSureQError, PayloadTooLargeError, Queue } from '@sureq/core'
type Email = { to: string; body: string }
const queue = new Queue<Email>('emails', { maxPayloadBytes: 1024 })
// 1. Errors thrown to the caller.
try {
await queue.add({ to: 'ada@example.com', body: 'x'.repeat(2000) })
} catch (err) {
if (err instanceof PayloadTooLargeError) console.log(err.code, err.size, '>', err.limit)
else throw err
}
try {
await queue.cancel('no-such-job')
} catch (err) {
if (isSureQError(err) && err.code === 'JOB_NOT_FOUND') console.log(err.code, err.message)
else throw err
}
// 2. Errors reported as events: store trouble, SureQ bugs, and your own listeners.
queue.on('error', ({ error, source, context }) => console.log('error event', source, context.event, error.code))
// 3. Job failures: the handler's error, stored on the job.
class BounceError extends Error {
name = 'BounceError'
code = 'MAIL_BOUNCE'
}
queue.process(
async (job) => {
throw new BounceError(`no mailbox for ${job.data.to}`)
},
)
queue.on('failed', ({ job, reason, error }) => {
console.log('failed', job.id, reason, error.name, error.code, error.message)
throw new Error('bug in my listener')
})
const drained = new Promise<void>((resolve) => queue.once('drained', () => resolve()))
await queue.add({ to: 'nobody@example.com', body: 'hi' }, { id: 'bounce', maxAttempts: 1 })
await drained
const stored = await queue.getJob('bounce')
console.log(stored?.state, stored?.error?.code)
await queue.close()Output:
PAYLOAD_TOO_LARGE 2034 > 1024
JOB_NOT_FOUND Job "no-such-job" was not found
failed bounce attempts-exhausted BounceError MAIL_BOUNCE no mailbox for nobody@example.com
error event listener failed LISTENER_ERROR
failed MAIL_BOUNCE- Calls throw for bad input or a bad state: here the data is over
maxPayloadBytes, and the id is unknown. Each error class has its own fields, such assizeandlimit. isSureQError(err)is true for any SureQ error, even from a second copy of the package. Thenerr.codetells you which one.- A handler's error is not thrown to you. It fails the attempt, and the job stores it as a
SerializedErrorwith itsname,message,codeand stack. Read it from thefailedevent orjob.error. - A stored error is plain data, not an
Errorobject, soinstanceofdoes not work on it. Checkerror.codeorerror.name. - The
errorevent carries problems that are not a job failure. A listener that throws never breaks SureQ; it shows up here withsource: 'listener'.
Common questions
What if I do not listen for error? Each one is logged instead. Listen on every queue and worker anyway, so store trouble reaches your own monitoring.
Which errors are worth retrying? A StoreError says so in retryable. When outcomeUnknown is true, read the job back before you repeat a write. See Errors: store.
How do I stop a handler error from being retried? Throw UnrecoverableError, or give the worker a retryIf. See Retries and failures.
Can I turn a stored error back into an Error? Yes, with deserializeError(job.error). It builds a plain Error, not the original class. See Stored errors.