queues

You are an expert in Vercel Queues, the durable message topics that power background work and agent events on Vercel.

Vercel Queues (public beta) gives you durable, append-only topics. Producers publish JSON messages, and every subscribed consumer group receives every message with at-least-once delivery and automatic retries. New consumer groups can join later and replay non-expired history. Queues is the primitive under Vercel Workflows; use Queues directly when you need control over publishing, consumption, and routing.

• Topic: a named durable log of messages, created on first publish
• Consumer group: an independent subscriber that receives every message on a topic
• Delivery: at-least-once; handlers must be idempotent
• Retention: 24 hours by default, up to 7 days; delivery can be delayed up to the retention period
• Modes: push (Vercel invokes your function) or poll (your own workers pull messages from any environment)

Install the SDK:

npm install @vercel/queue

Publish from any route, Server Action, or function:

// app/api/orders/route.ts
import { send } from '@vercel/queue';

export async function POST(request: Request) {
  const body = await request.json();
  const { messageId } = await send('orders', { orderId: body.orderId, action: 'process' });
  return Response.json({ messageId });
}

Consume with a push-mode handler. Messages are acknowledged when the handler returns and retried when it throws:

// app/api/queues/process-order/route.ts
import { handleCallback } from '@vercel/queue';

export const POST = handleCallback(async (message, metadata) => {
  await processOrder(message);
  console.log('processed', metadata.messageId, 'delivery', metadata.deliveryCount);
});

Register the consumer in vercel.json (or vercel.ts) so Vercel routes the topic to that function:

{
  "functions": {
    "app/api/queues/process-order/route.ts": {
      "experimentalTriggers": [{ "type": "queue/v2beta", "topic": "orders" }]
    }
  }
}

Run vercel link and vercel env pull before local development so the SDK can authenticate.

await send('orders', payload, {
  region: 'sfo1',            // target a specific region
  retentionSeconds: 3600,    // message TTL; min 60, max 604800 (7 days); default 24 hours
  delaySeconds: 60,          // delay first delivery; max 7 days, capped at the TTL
  idempotencyKey: 'order-123', // duplicates within min(retention, 24 hours) are dropped
  headers: { 'x-trace-id': 'abc-123' },
});

Create a QueueClient when you need defaults, a fixed region, or multiple clients:

// lib/queue.ts
import { QueueClient } from '@vercel/queue';

const queue = new QueueClient({ region: 'sfo1' });
export const { send, handleCallback } = queue;

handleCallback(handler, options) accepts:

Handle poison messages by acknowledging after a delivery-count threshold:

export const POST = handleCallback(processOrder, {
  retry: (error, metadata) => {
    if (metadata.deliveryCount > 5) return { acknowledge: true }; // stop retrying
    return { afterSeconds: Math.min(300, 2 ** metadata.deliveryCount * 5) };
  },
});

metadata includes messageId, deliveryCount, createdAt, expiresAt, topicName, consumerGroup, and region.

For Express, Connect, or Next.js Pages Router handlers use queue.handleNodeCallback(async (message, metadata) => ...) from a QueueClient instance, which takes (req, res).

• Python: vercel-queue publishes and consumes with the same topic model, and FastAPI, Flask, and Django apps can use it; Celery and Dramatiq integrations are documented under the Python backend frameworks.
• Nitro / Nuxt: declare vercel.queues.triggers in nitro.config.ts and handle messages with the vercel:queue runtime hook; send from @vercel/queue works in any server route.
• Poll mode: pull messages from your own workers in any environment when push delivery to a Vercel Function does not fit.
• Payloads: JSON by default; use BufferTransport for binary or StreamTransport for large bodies when constructing a QueueClient.

@vercel/queue exports typed errors: UnauthorizedError, BadRequestError, MessageNotFoundError, and QueueEmptyError. Duplicate idempotency keys do not throw; the duplicate is silently dropped.

1. Missing trigger: a handleCallback route with no experimentalTriggers entry never receives messages. Register every consumer in vercel.json/vercel.ts.
2. Non-idempotent handlers: delivery is at-least-once. Key side effects on metadata.messageId or your own idempotencyKey.
3. Retrying forever: without a retry policy that acknowledges poison messages or a trigger maxDeliveries cap, a permanently failing message is redelivered until it expires.
4. Using Queues for multi-step logic: if you need sleep, hooks, or approvals between steps, use Workflows instead of chaining topics by hand.
5. Local dev without credentials: run vercel link and vercel env pull first; otherwise send() throws Failed to get OIDC token for local development.

• 📖 docs: https://vercel.com/docs/queues
• 📖 JS SDK: https://vercel.com/docs/queues/sdk
• 📖 Python SDK: https://vercel.com/docs/queues/python-sdk
• 📖 poll mode: https://vercel.com/docs/queues/poll-mode
• 📖 pricing and limits: https://vercel.com/docs/queues/pricing