Skip to main content

Queues and outbox

Symptoms​

Orders commit but fulfillment never starts. Channel sync does not run. OutboxEvent stays PENDING or becomes DEAD. Bull Board shows failed jobs.

Likely causes​

  • The worker is not running. The API does not dispatch the outbox.
  • The scheduler is not running. Sync and the 3-hour tracking poll are crons.
  • You emitted an in-process event from the API and the listener is only loaded on the worker.
  • The event is return.status.changed or return.stock.restored, which have no listener.
  • The channel is SUSPENDED or INACTIVE, or the tenant or subscription is inactive.
  • The job processor caught the error and returned, so Bull did not retry.
  • Attempts reached 10 and the row is DEAD.

How to investigate​

  • Confirm three processes. See Running the backend.
  • Open Bull Board at /admin/queues with BULL_BOARD_USER and BULL_BOARD_PASSWORD. Not every queue is on the board.
  • Query OutboxEvent for the aggregate id. Read status, attempts, and lastError.
  • PROCESSING older than 5 minutes should return to PENDING on the next dispatcher loop without incrementing attempts.

Useful commands​

yarn start:worker
yarn start:scheduler

There is no documented CLI to replay a DEAD row.

Resolution​

Start the missing process. Fix the listener exception and, if the row is DEAD, replay is a manual database change.

Unknown — requires developer confirmation: the supported way to move DEAD back to PENDING, and who is allowed to set a SUSPENDED channel back to ACTIVE.

Midnight cron​

MidNightScheduleWorker at 0 0 * * * only logs. It is not a sign that business maintenance ran.