Troubleshooting

onBoot does nothing

@quik/queue-worker's onBoot hook only runs when the app is booted inside a worker_threads worker (!isMainThread && parentPort). Booting the app on the main thread with this module included is a no-op by design — boot it inside a dedicated worker entry file instead.

Worker never processes tasks

No execute hook is registered by default — register one with WorkerHooks.register('execute', handler) (typically done by the module that owns the queue, such as @quik/scheduler's database executor).

Worker doesn't shut down

shutdown messages set a flag but wait for any in-flight tick to finish before exiting. If a registered execute handler hangs indefinitely, the worker will never reach the shutdown path — ensure handlers have their own timeouts.

Database connection errors after restart

The worker closes its database connection during shutdown. If you restart a worker via postMessage({ type: 'restart' }) rather than spawning a new Worker, ensure your restart hook re-establishes any connections it depends on.