Running background workers on Vercel

Copy link to headingCan you run background workers on Vercel?

Yes, Vercel runs background work. Use waitUntil for short tasks that can finish after the response, Cron Jobs for schedules, Vercel Queues for event-driven jobs with retries, and Vercel Workflows for multi-step jobs with durable waits.

Vercel Daemons keep workers running so they can pull new jobs. Use them for Celery processes and queue consumers that run ffmpeg.

Copy link to headingWhich background work option should you use on Vercel?

Choose a background work option by how long the job runs and what starts it.

With Fluid compute enabled, Vercel Functions have a default max duration of 300 seconds on every plan. Pro and Enterprise teams can raise it to 800 seconds, or to 1,800 seconds (30 minutes) in beta for supported Node.js, Bun, and Python runtimes (duration docs). Sandbox has separate session duration limits.

Vercel Workflows has been generally available since April 2026. Vercel Queues and Vercel Daemons are in public beta. During the beta, Vercel Daemons run only in production, don't autoscale, and can't receive inbound traffic.

Compare Functions, containers, and Daemons to choose a compute type. For job delivery and durable orchestration, weigh Queues against Workflows.

Copy link to headingHow do you run a task after the response on Vercel?

Use waitUntil from @vercel/functions to let an asynchronous task continue after a Vercel Function sends its response. The task starts when you create the promise, and waitUntil keeps the invocation alive within its existing max duration.

In Next.js 15.1 and later, use after() from next/server to schedule a callback that starts after the response.

Copy link to headingExample: send a welcome email after signup

This signup route creates the account and starts the welcome email without waiting for it to finish before returning the response:

import { waitUntil } from '@vercel/functions';
import { createUser, sendWelcomeEmail } from '@/lib/users';

export async function POST(request: Request) {
  const { email } = await request.json();
  const user = await createUser(email);

  // Let the email task continue within this invocation's max duration.
  waitUntil(sendWelcomeEmail(user));

  return Response.json({ id: user.id });
}

In the App Router, after() runs the email callback after the response:

import { after } from 'next/server';
import { createUser, sendWelcomeEmail } from '@/lib/users';

export async function POST(request: Request) {
  const { email } = await request.json();
  const user = await createUser(email);

  after(() => sendWelcomeEmail(user));

  return Response.json({ id: user.id });
}

Copy link to headingWhen does waitUntil stop being enough?

waitUntil provides no retries, queue, or task record. If the email provider fails or the function hits its max duration, the task is lost. That trade-off suits logging, analytics, and cache warming that tolerate occasional task loss.

Use Vercel Queues for tasks that need retries, or Vercel Workflows for jobs with several steps or waits. See the waitUntil API for details.

Copy link to headingHow do you run scheduled jobs on Vercel?

Use Cron Jobs to run a Vercel Function on a schedule defined in vercel.json. Vercel sends an HTTP GET request to the configured path on your production deployment. Each run must finish within the function's max duration.

Copy link to headingExample: sync data from a CRM every night

This schedules /api/sync-crm daily at 05:00 UTC. Hobby may invoke it within that hour; Pro and Enterprise schedule to the minute:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "crons": [
    {
      "path": "/api/sync-crm",
      "schedule": "0 5 * * *"
    }
  ]
}

Set a random CRON_SECRET of at least 16 characters in your production environment. Vercel sends cron requests with Authorization: Bearer <CRON_SECRET>.

Reject requests if the secret is missing or the header doesn't match.

Save this public Next.js App Router handler as app/api/sync-crm/route.ts:

import { syncContactsFromCrm } from '@/lib/crm';

export const maxDuration = 300;

export async function GET(request: Request) {
  const secret = process.env.CRON_SECRET;
  const authorization = request.headers.get('authorization');

  if (!secret || authorization !== `Bearer ${secret}`) {
    return new Response('Unauthorized', { status: 401 });
  }

  const synced = await syncContactsFromCrm();
  return Response.json({ synced });
}

Cron Jobs run only in production. See Securing cron jobs for CRON_SECRET setup.

Cron delivery can be missed or duplicated, and Vercel does not retry a failed invocation. Make the sync safe to repeat and reconcile changes since its last successful run. Hobby supports one run per day for each cron job; Pro and Enterprise support intervals as short as one minute.

Copy link to headingWhen should a scheduled job use Vercel Workflows?

Scheduled jobs that need durable retries, have several steps, or may exceed the function's max duration should start a workflow from the cron route.

Call start() from the Workflow SDK and leave retries and state to the workflow. Follow the Next.js background jobs pattern for this setup.

Starting a workflow does not recover a cron invocation that never reached the route. Use the next scheduled run to reconcile missed work.

Copy link to headingHow do you process jobs from a queue on Vercel?

Use Vercel Queues in push mode to process jobs as events arrive. Your app publishes a message to a topic, and Vercel invokes a private consumer function for each message, retrying failed deliveries until the message expires or reaches a configured delivery cap. The consumer's max duration applies to each delivery. Plan how to handle messages that keep failing once retries stop.

Vercel Queues delivers each message at least once, so consumers must be safe to run twice. Design consumers for idempotency, so a repeated delivery has the same effect as the first. Consumer functions have no public URL, which means only Vercel's queue infrastructure can invoke them.

Copy link to headingExample: resize images when users upload them

Image processing can fail on a bad file or a slow storage call. Vercel Queues buffers jobs from upload bursts and retries failures until message retention expires.

Save this subscriber as queues/uploads.py. It limits the consumer group to 10 concurrent deliveries and calls an application-owned app_clients.images helper:

from pydantic import BaseModel
from vercel.queue import Topic, subscribe

from app_clients import images


class Upload(BaseModel):
    upload_id: str
    blob_url: str


uploads = Topic[Upload]("image-uploads")


@subscribe(topic=uploads, consumer_group="thumbnails", max_concurrency=10)
async def make_thumbnail(upload: Upload) -> None:
    # This application helper must publish the completed image idempotently.
    await images.resize_and_store(
        source=upload.blob_url,
        destination=f"thumbnails/{upload.upload_id}.webp",
        width=400,
    )

Implement resize_and_store for immutable source uploads and atomic publication of a completed thumbnail. For example, conditionally create the destination object and treat an existing thumbnail for the same upload and resize settings as success. The destination path alone does not make concurrent retries safe.

Register the module in pyproject.toml to build a private queue consumer:

[[tool.vercel.subscribers]]
entrypoint = "queues.uploads"

Call this helper from your upload route to publish the message. The same upload ID produces the same idempotency key, so repeated publishes are deduplicated within the message's retention window, up to 24 hours:

from vercel.queue import send

from queues.uploads import Upload, uploads


async def queue_thumbnail(upload: Upload) -> None:
    await send(uploads, upload, idempotency_key=f"thumb-{upload.upload_id}")

Copy link to headingWhich settings control retries and load?

JavaScript and TypeScript consumers declare their triggers in vercel.json:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "functions": {
    "app/api/queues/make-thumbnail/route.ts": {
      "experimentalTriggers": [
        {
          "type": "queue/v2beta",
          "topic": "image-uploads",
          "retryAfterSeconds": 60,
          "maxDeliveries": 10
        }
      ]
    }
  }
}

The JavaScript SDK and the queue/v2beta trigger don't document a max concurrency option yet. To cap concurrency from JavaScript, consume the topic in poll mode from a Vercel Daemon, where the number of instances and loops sets how many messages run at once.

Set up a Python queue consumer with FastAPI, retries, and tests.

Copy link to headingWhen should you use poll mode?

Use poll mode when the consumer needs to decide when to pull work, or when it runs outside Vercel. Poll-mode consumers often run as Vercel Daemons, which keep pulling messages without a per-message function invocation.

Copy link to headingHow do you run multi-step or long-running jobs on Vercel?

Use Vercel Workflows for jobs with several steps, waits, or external events. Workflows are async functions marked with "use workflow", and each unit of external work is a "use step" function. Vercel records every step's result, so a workflow can retry a failed step, sleep for minutes to months without using compute, and resume after a crash or a new deployment.

Workflows run on Vercel Functions and Vercel Queues, but no single function needs to run for the whole job. Each step runs in its own invocation and must finish within the function's max duration.

Copy link to headingExample: fulfill an order and request a review three days later

This workflow charges an order, reserves stock, creates a shipment, and sends a shipping email. After a three-day wait, it requests a review. Each step can run again after a failure, so its external calls must be safe to repeat.

The example assumes application-owned clients exported from @/lib/order-integrations. Each client must enforce the operation key through its provider's idempotency API or a durable record coordinated with the side effect. An option named idempotencyKey does not enforce this contract.

import { sleep, FatalError } from 'workflow';
import { payments, inventory, warehouse, email } from '@/lib/order-integrations';

export async function fulfillOrder(orderId: string) {
  'use workflow';

  const charge = await chargeCard(orderId);
  await reserveStock(orderId);
  const shipment = await createShipment(orderId);
  await sendShippingEmail(orderId, shipment.trackingUrl);

  await sleep('3d');
  await sendReviewRequest(orderId);

  return { orderId, chargeId: charge.id };
}

async function chargeCard(orderId: string) {
  'use step';
  const result = await payments.charge(orderId, {
    idempotencyKey: `charge-${orderId}`,
  });
  if (result.declined) {
    throw new FatalError('Card declined');
  }
  return result;
}

async function reserveStock(orderId: string) {
  'use step';
  await inventory.reserve(orderId, {
    idempotencyKey: `reserve-${orderId}`,
  });
}

async function createShipment(orderId: string) {
  'use step';
  return warehouse.createShipment(orderId, {
    idempotencyKey: `ship-${orderId}`,
  });
}

async function sendShippingEmail(orderId: string, trackingUrl: string) {
  'use step';
  await email.send({
    template: 'shipped',
    orderId,
    trackingUrl,
    idempotencyKey: `shipping-email-${orderId}`,
  });
}

async function sendReviewRequest(orderId: string) {
  'use step';
  await email.send({
    template: 'review-request',
    orderId,
    idempotencyKey: `review-email-${orderId}`,
  });
}

Start the workflow from a route handler and respond right away:

import { start } from 'workflow/api';
import { fulfillOrder } from '@/workflows/fulfill-order';

export async function POST(request: Request) {
  const { orderId } = await request.json();
  await start(fulfillOrder, [orderId]);
  return Response.json({ status: 'processing' });
}

Unhandled step errors retry up to three times by default; FatalError stops retries. Keep the same operation key across attempts and retain records of completed business operations for as long as those operations can be replayed.

The application must deduplicate order submissions because repeated requests can start new workflow runs. See step and run deduplication.

Copy link to headingWhy use Workflows instead of chaining queues?

You can build the same order flow by publishing a message at the end of each consumer, but you then own the state between steps, including which steps succeeded before a failure.

The three-day wait needs a delayed message with enough retention left for processing and retries. Queues retains messages for 24 hours by default; both retention and delivery delay can be extended to 7 days.

Vercel Workflows keeps that state in an event log. If the shipment fails, Vercel Workflows retries only createShipment, not the charge, and the dashboard shows every run and step. Use Vercel Queues directly when you need raw throughput or fine-grained control over consumer groups, and use Vercel Workflows for business processes with steps and waits. For a fuller comparison, see when to use queues vs. workflows.

For setup, retries, and hooks that wait for webhooks, see the Next.js workflow walkthrough and workflow concepts. Vercel Workflows also supports Python.

Copy link to headingHow do you run an always-on worker on Vercel?

Use Vercel Daemons for containerized workers that stay running and pull work. Declare each daemon in vercel.json with a Dockerfile. Vercel builds the image, starts the configured instances in each region, and restarts any instance that exits. Daemons run on Fluid compute, the same platform as Vercel Functions.

Vercel Daemons don't receive traffic. Each instance pulls from a queue, job database, workflow engine, or external API. This suits workers built with Celery, Sidekiq, BullMQ, or Temporal.

Still comparing Daemons with container services or a VPS? See where to host background workers.

During the public beta, Vercel Daemons have these constraints:

• Daemons run only in production. Preview deployments don't start them.
• Daemons don't autoscale. Set 0 to 100 instances per region in vercel.json or the dashboard, within the plan and project quotas listed below.
• Each instance runs on Linux amd64. Hobby supports 1 or 2 GiB with 1 vCPU. Pro and Enterprise also support 4 GiB with 2 vCPUs and 8 GiB with 4 vCPUs. The default is 2 GiB.
• For rollouts, scale-downs, and removal, Vercel sends SIGTERM and waits 30 seconds by default. Set terminationGracePeriodSeconds to allow up to 3,600 seconds.
• The project's root directory must be the repository root.

Copy link to headingExample: transcode uploaded videos with ffmpeg

Use a daemon when the video processor continuously polls for uploads or handles transcodes that exceed the function's max duration. The app publishes one job to Vercel Queues per upload, and a Python worker runs ffmpeg for each job.

The processor's Dockerfile installs ffmpeg alongside the Python dependencies:

FROM python:3.12-slim
RUN apt-get update \
    && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY processor.py .
CMD ["python", "processor.py"]

Declare the daemon next to your app in vercel.json. On Pro or Enterprise, this configuration runs two instances in iad1, each with 4 GiB of memory and 2 vCPUs. It allows up to 10 minutes to finish a transcode after SIGTERM:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "daemons": {
    "videos": {
      "root": "processor/",
      "entrypoint": "Dockerfile",
      "instances": { "iad1": 2 },
      "resources": { "requests": { "memory": "4Gi" } },
      "terminationGracePeriodSeconds": 600
    }
  }
}

The processor loop should poll the queue, stop accepting new jobs when it receives SIGTERM, and acknowledge each message only after the transcoded file is stored. If an instance stops mid-job, the unacknowledged message becomes visible again after its visibility timeout, and another instance picks it up. Use the Python polling worker for a complete implementation.

Copy link to headingExample: move a Celery worker from Heroku

Heroku apps often start Celery from a Procfile entry such as worker: celery -A app worker --loglevel=info. Run that command as a Vercel Daemon using your existing backend image and broker:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "daemons": {
    "celery": {
      "root": "backend/",
      "entrypoint": "Dockerfile",
      "command": ["celery", "-A", "app", "worker", "--loglevel=info"],
      "instances": { "iad1": 1 }
    }
  }
}

The worker can keep its task code and broker. Set its broker URL through a production environment variable such as CELERY_BROKER_URL.

Celery acknowledges tasks before execution by default. For idempotent tasks that must return to the queue after an interruption, configure late acknowledgment with task_acks_late. Review task_reject_on_worker_lost if tasks should also be requeued after the executing child process exits abruptly.

Set terminationGracePeriodSeconds long enough for normal tasks to finish, then test forced interruption as well as graceful shutdown.

Verify recovery behavior before moving production work:

1. Deploy the daemon with the same broker and task definitions as the Heroku worker.
2. Confirm that the daemon processes jobs. Test that graceful shutdown finishes a job and that forced termination recovers a job under your chosen acknowledgment policy.
3. Scale the Heroku worker dyno to zero, then remove it.

Vercel runs command directly, so environment variables in the array aren't expanded. To use WORKER_CONCURRENCY, replace the daemon's command value with:

[
  "sh",
  "-c",
  "exec celery -A app worker --concurrency \"$WORKER_CONCURRENCY\""
]

Moving a worker doesn't move the jobs stored in its broker. If the broker is also changing, for example from Heroku Data for Redis to a Marketplace provider, migrate the broker first and account for delayed jobs and scheduled retries. Moving workers from Render instead? Follow the steps to migrate Render workers to Vercel Daemons.

Learn to configure, scale, and monitor daemons and test them locally with Docker.

Copy link to headingHow do you run AI agents in the background on Vercel?

Use Vercel Workflows to coordinate steps around an agent call, such as generating a report, waiting for approval, and publishing it. Vercel Queues in push mode delivers agent jobs to functions when you don't need to control polling.

Choose Vercel Daemons for workers that need to control the pull rate, hold connections open, or run tools that need system binaries. Keep durable sessions in the agent framework and use the daemon to feed them work or perform CPU-heavy tasks while a session waits.

Vercel Sandbox isolates agent-generated code from your app's credentials.

Copy link to headingHow do you run eve agents with Vercel Daemons?

Within the eve agent's Vercel project, a daemon takes a queued job and starts a session through POST /eve/v1/session. It reads the session stream and acknowledges the job after the turn completes or its failure is saved for review.

An eve tool can also hand heavy work to a daemon through Vercel Queues. The session waits without holding compute until the daemon posts the result.

Keep vercelOidc() in the agent's eve channel auth list so it accepts the same project's daemon identity. The daemon reads its rotating token file for each request. Use operationId for session creation and idempotencyKey for follow-up messages.

This excerpt uses the shared worker dependencies and helpers. It keys operationId on the queue message ID so redelivery can reconnect to the existing session while that session remains resumable.

import { PollingQueueClient } from '@vercel/queue';
import { startSession, waitForFirstTurn } from './lib/eve.ts';
import { idle, shutdown } from './lib/shutdown.ts';

interface Ticket {
  id: string;
  subject: string;
  body: string;
}

const queue = new PollingQueueClient({
  region: 'iad1',
  deploymentId: null,
});

async function handleTicket(
  ticket: Ticket,
  metadata: { messageId: string },
): Promise<void> {
  shutdown.signal.throwIfAborted();
  const sessionId = await startSession(
    [
      `Triage support ticket ${ticket.id}.`,
      `Subject: ${ticket.subject}`,
      '',
      ticket.body,
    ].join('\n'),
    `ticket-${metadata.messageId}`,
  );
  const turn = await waitForFirstTurn(sessionId, shutdown.signal);
  if (turn.outcome !== 'completed') {
    await queue.send(
      'support-tickets-failures',
      {
        ticket,
        messageId: metadata.messageId,
        sessionId,
        outcome: turn.outcome,
      },
      {
        idempotencyKey: `triage-failed-${metadata.messageId}`,
        retentionSeconds: 604800,
      },
    );
    console.error(`Triage ${turn.outcome} for ticket ${ticket.id}`);
  }
}

while (!shutdown.signal.aborted) {
  try {
    const result = await queue.receive<Ticket>(
      'support-tickets',
      'triage-agent',
      handleTicket,
    );
    if (!result.ok) await idle(2000);
  } catch (error) {
    if (!shutdown.signal.aborted) console.error(error);
    await idle(2000);
  }
}
process.exit(0);

Session request or stream errors leave the ticket unacknowledged so redelivery can reconnect. Failed or cancelled turns go to support-tickets-failures before the original ticket is acknowledged.

Connect the failure collector before deploying. It saves records to Postgres before the failure topic's seven-day retention expires.

Creation deduplication applies to the same authenticated caller while the session remains resumable. Concurrent creates can return different IDs during startup, and an ended session frees its operationId for reuse.

Check durable job outcomes before starting work again after a session ends. Follow-up messages retain the most recent 1,024 idempotencyKey values. See the eve channel reference for the full contract.

The full guide also demonstrates these worker patterns:

• Keep a Postgres LISTEN connection open to start a fraud review whenever your database flags an order.
• Rewrite 12,000 product descriptions, with one session per product.
• Check error rates every 15 seconds and investigate threshold breaches.

Copy link to headingHow do you run Mastra workers with Vercel Daemons?

Run Mastra's orchestration and background-task workers as a daemon, using Mastra's split-process setup. The Mastra API keeps serving HTTP requests, and the worker pulls tasks from a shared PubSub backend. Configure both processes with the same storage and PubSub:

• Shared state: Configure both processes with the same remote storage and pull-capable PubSub. For example, use PostgresStore from @mastra/pg and RedisStreamsPubSub from @mastra/redis-streams.

  Set matching DATABASE_URL and REDIS_URL values.

• API process: Set MASTRA_WORKERS=false so the API doesn't run workers itself.
• Worker callbacks: Set MASTRA_STEP_EXECUTION_URL to the worker-callable API URL, including /api, and MASTRA_WORKER_AUTH_TOKEN to a bearer token the API accepts. The endpoint must also be reachable through Deployment Protection. If the main API requires Passport visitor identity, use a separate API deployment with machine authentication for callbacks.
• Scheduler: Leave Mastra's scheduler out of the daemon. It needs exclusive ownership and can run jobs twice while two deployments overlap.

Exclude .env*, node_modules, .mastra, and .vercel in the application's .dockerignore. Keep database, PubSub, and worker authentication credentials in the project's production environment variables.

Build the worker with mastra worker build inside the container, so its dependencies match the Linux runtime. Save this file as Dockerfile.worker at the application root:

FROM node:24-slim AS build
WORKDIR /app
RUN corepack enable
COPY . .
RUN pnpm install --frozen-lockfile
RUN pnpm exec mastra worker build --output-dir .mastra/worker

FROM node:24-slim
WORKDIR /app
COPY --from=build /app/.mastra/worker/ ./
CMD ["sh", "-c", "MASTRA_WORKERS=orchestration exec node index.mjs"]

Then declare the daemon in vercel.json:

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "daemons": {
    "mastra-worker": {
      "root": ".",
      "entrypoint": "Dockerfile.worker",
      "instances": { "iad1": 1 },
      "terminationGracePeriodSeconds": 60
    }
  }
}

To run background tasks instead of orchestration, set MASTRA_WORKERS=backgroundTasks in the CMD. Follow the Mastra worker setup for authentication and shutdown details.

Copy link to headingWhat applies to every agent framework on Vercel Daemons?

• Production only: Vercel Daemons run only in production during the beta, so test workers locally with Docker.
• Idempotent handlers: Restarting a daemon doesn't checkpoint an agent's progress, and a retried job can repeat a tool call. Pass stable idempotency keys to every API that changes data.
• OIDC from a file: Read VERCEL_OIDC_TOKEN_FILE with @vercel/oidc 4.0.0 or later, or vercel-oidc 0.10.0 or later in Python. Vercel refreshes the file, so don't copy the token into a long-lived environment variable. Check that SDKs making authenticated calls use a file-aware OIDC dependency too.

• Concurrency and budgets: Instance and loop counts control how many jobs the workers handle at once. Agent sessions can continue after a worker disconnects, and deployments overlap, so a strict limit needs shared permits held until each session settles.

  Set model rate limits and per-session usage limits separately.

Copy link to headingHow do you move existing workers to Vercel?

Vercel Daemons can run existing pull-based workers in containers. Check broker connectivity, Linux amd64 dependencies, shutdown behavior, and any local state before moving the worker. Store persistent state in a database or object store.

You can move work gradually by having both platforms consume compatible jobs from the same broker. If the broker is also changing, migrate it separately and account for jobs already queued.

Copy link to headingMigration guides by platform

The Heroku guide moves worker dynos to Vercel Queues and Heroku Scheduler jobs to Cron Jobs. To keep the Celery worker process instead, follow the Celery example in the Vercel Daemons section of this guide.

Copy link to headingMigration guides by worker framework

Celery has two paths. Run the existing worker as a daemon to retain its broker and task model, after checking the migration requirements above. Or adapt tasks to Vercel Queues so Vercel invokes and scales each consumer.

Copy link to headingWhat does background work cost on Vercel?

Vercel Functions and Vercel Daemons bill for Active CPU and Provisioned Memory. Active CPU billing pauses while code waits on I/O. Vercel Queues adds API-operation charges, and Vercel Workflows adds event and data charges.

Several billing details change which option is cheaper:

• Idle daemons still use memory: An idle daemon instance uses no Active CPU, but its Provisioned Memory counts every hour it runs. One 2 GiB instance running all month uses about 1,460 GB-hours.
• Hobby daemon quotas: Hobby teams get 5 Active CPU-hours and 420 GB-hours of Provisioned Memory per month for daemons across all projects. Vercel stops all of the team's daemons when either quota runs out, so use Pro for workers that run all month.
• Queue options cost extra: Sends with an idempotency key, and push deliveries with a max concurrency, bill at 2x units for that operation.
• Failed deliveries cost compute: Push deliveries that time out bill the consumer function's full maxDuration at its configured memory. Set maxDeliveries and a retry depth alert to limit runaway retries.
• Workflow steps produce events: Every normal step produces three events, and each retry adds one more. Hobby includes 50,000 events per month.
• Agent runs add model charges: Daemons running AI agents also incur model usage, for example through AI Gateway. Control throughput with worker concurrency, and set model budgets and per-session usage limits separately.

Copy link to headingHow do you handle failures and duplicates in background jobs on Vercel?

Assume every background job can run more than once. Vercel Queues delivers each message at least once, Vercel Workflows retries steps, and a daemon instance can stop mid-job during a deployment. Design each job so a second run produces the same result as the first.

Copy link to headingMake consumers idempotent

• Deduplicate publishes: Pass an idempotency key to send(). Vercel Queues drops a repeat publish with the same key for the shorter of 24 hours and the message's retention period.
• Use stable job keys: Pass keys such as charge-${orderId} to payment, email, and shipping APIs that support idempotency.
• Write by key, not by increment: Use upserts or unique constraints, and set values rather than adding to them.
• Acknowledge last: Acknowledge a queue message only after the work succeeds. An unacknowledged message becomes visible again after its visibility timeout. The JavaScript SDK's handleCallback sets a 5-minute timeout and extends it while the handler runs, and the Queues API default is 60 seconds.

Copy link to headingHandle messages that keep failing

Vercel Queues has no built-in dead-letter queue. maxDeliveries stops further deliveries without saving the payload elsewhere. To preserve failed jobs, record the payload durably inside the handler before it returns successfully.

The handler saves a failure record after 10 unsuccessful fulfillment attempts:

import { handleCallback } from '@vercel/queue';
import { fulfillOrder, recordFailedOrder } from '@/lib/orders';

type Order = Parameters<typeof fulfillOrder>[0];

export const POST = handleCallback<Order>(
  async (order, metadata) => {
    try {
      await fulfillOrder(order);
    } catch (error) {
      if (metadata.deliveryCount < 10) throw error;

      // Application helper: durably upsert by messageId before acknowledging.
      await recordFailedOrder({
        messageId: metadata.messageId,
        order,
        error: String(error),
      });
    }
  },
  {
    retry: (_error, metadata) => ({
      afterSeconds: Math.min(300, 2 ** metadata.deliveryCount * 5),
    }),
  },
);

Implement recordFailedOrder as a durable upsert keyed by messageId. If it fails, the handler throws and the message remains eligible for retry. Leave maxDeliveries unset for this example so it does not cut off attempts to save the failure record.

Retries still end when the message expires, so monitor failed-record writes and keep the original job in durable application storage if it must survive queue expiry. See the Python Queues guide for another failure-handling example.

Copy link to headingStop a failing deployment's consumers

In push mode, messages stay pinned to the deployment that published them, so promoting a fix doesn't stop deliveries to the old deployment. Its consumers keep running and retrying for up to the message retention period, 24 hours by default.

Deleting the old deployment stops its consumers immediately, but the replacement deployment will not automatically process its pending messages. Preserve any jobs you need to replay before deletion; otherwise they remain queued until expiry. If the deployment also owns workflow runs, cancel those runs before deleting it.

Pending messages use no function compute after deletion. In Observability, group function duration by deployment to identify the consumers that are still running.

Copy link to headingShut daemons down cleanly

The terminationGracePeriodSeconds setting controls how long Vercel waits after SIGTERM during a rollout, scale-down, or removal. Stop taking new work and finish the current job within that window.

Make retries safe and leave unfinished messages unacknowledged, since crashes and liveness-triggered restarts can interrupt work immediately. During deployments, overlapping versions must accept compatible messages.

Copy link to headingWhat are the limits for background work on Vercel?

The function max duration limits waitUntil, Cron Jobs, Vercel Queues push consumers, and each Vercel Workflows step. Vercel Workflows runs and Vercel Daemons have no overall duration limit.

Copy link to headingVercel Functions max duration

These limits apply with Fluid compute, the default for new projects.

During the beta, durations above 800 seconds must be set per function, and Secure Compute and Static IPs don't support them. See Configuring maximum duration.

Copy link to headingVercel Queues limits (public beta)

See Queues pricing and limits.

Copy link to headingVercel Workflows limits

See Workflows pricing and limits.

Copy link to headingVercel Daemons limits (public beta)

See Daemons limits.

Copy link to headingVercel Sandbox limits

Vercel Sandbox sessions run for 5 minutes by default, and up to 45 minutes on Hobby or 24 hours on Pro and Enterprise. See session duration and persistence and Sandbox pricing and limits.

Copy link to headingNext steps

• Choose a compute type with Functions, containers, and Daemons.
• Build Next.js background jobs with Vercel Workflows.
• Build Python queue consumers and review how delivery works.
• Configure always-on workers with Vercel Daemons.
• Run background agents with eve on Vercel Daemons or Mastra on Vercel.
• Schedule jobs with Cron Jobs.
• Run untrusted code with Vercel Sandbox.