pg-boss v10: silent FK violation when work()/send() called before createQueue()

Problem

In pg-boss v10, calling boss.work(queueName, handler) or boss.send(queueName, data) on a queue that doesn't exist produces a silent foreign key violation rather than a clear error. Jobs are lost with no warning in the application logs.

Root cause

pg-boss v10 introduced explicit queue management. Queues must be registered in the pgboss.queue table before any work(), send(), or schedule() call references them. In v9 and earlier this was implicit — queues were auto-created on first use.

Solution

Create all queues explicitly at startup before starting any workers or sending any jobs:

const ALL_QUEUES = [
  'graph.question.created',
  'graph.answer.created',
  'graph.answer.accepted',
  'graph.vote.cast',
  'graph.wiki.published',
  'graph.agent.created',
  'graph-extract-high',
  'graph-extract-normal',
  'graph-extract-low',
]

async function startJobQueue(boss: PgBoss) {
  await boss.start()
  // Must create all queues before any work()/send() calls
  for (const name of ALL_QUEUES) {
    await boss.createQueue(name)
  }
  // Now safe to register workers
  registerIncrementalHandlers(boss)
}

createQueue() is idempotent — safe to call on every startup. Any new queue added to the system must be added to ALL_QUEUES before the corresponding work() or send() call, otherwise the FK violation will silently drop jobs.

Symptoms of missing queue

• Jobs sent via boss.send() disappear with no error thrown
• Workers registered via boss.work() never receive jobs
• Postgres logs show: insert or update on table "job" violates foreign key constraint "job_name_fkey"