Queues

A queue is a to-do list for your app. Your app drops a message in; a single worker later picks it up, does the work, and confirms it. If the worker fails, the message comes back and is retried. Queues are how you run slow or spiky work in the background without making users wait and without losing anything. Open Backend → App Services → Queues to manage them.

Queues are per environment. A queue named order-processing in development is a different queue from one with the same name in production.

The queue list

The landing view lists every queue in the current environment, with live health that refreshes automatically:

Column	Plain meaning	Technical term
Name	The queue’s identifier (with a copy button).	—
Pending	Messages waiting to be picked up.	Queue depth
In flight	Messages a worker has taken but not yet confirmed.	In-flight
Oldest	How long the oldest waiting message has been sitting there (e.g., “3 d ago”).	Age of oldest message
Errors	Messages that failed too many times and moved to the error list. A red badge appears when this is above zero.	Dead-letter queue (DLQ) size

A steadily growing Pending count means messages arrive faster than your workers drain them — add workers or speed up processing. A growing Errors count means something is repeatedly failing — open the error list to investigate.

Create a queue

Creating a queue is meant to take about ten seconds — the only required field is the name.

Click New queue

In the Queues panel, click New queue.

Name it

Type a name. Names are lowercase letters, numbers and hyphens, with no spaces (they become part of an internal address). If what you type contains other characters, the panel shows the cleaned-up version it will use, and warns you immediately if the name is already taken.

(Optional) Adjust the configuration

The Configuration (recommended defaults) section is pre-filled with sensible values. Change them only if you need to — see the table below.

Create the queue

Click Create queue. The queue appears in the list, ready to receive messages.

Settings, explained

Every setting has a safe default, shown under Configuration (recommended defaults). You can change them later from the queue’s Configuration tab.

Setting (panel label)	Default	Range	What it controls (plain language)	Technical term
Processing time (s)	30 seconds	up to 12 hours	How long a consumer has to process a message before it’s retried. Set it a little longer than your slowest job.	Visibility timeout
Attempts before moving to errors	5	1–20	How many times a message is retried before it goes to the dead-letter queue (error list).	Max delivery / max receives
Message retention (days)	4 days	up to 14 days	How long an unprocessed message is kept before it expires.	Message retention

Processing time is the most common source of surprises. If a job legitimately takes longer than this window, another worker may start processing the same message in parallel. Set it comfortably above your slowest realistic job, or have the worker extend it while it works.

The queue detail view

Click any queue to open its detail, organized into tabs.

Summary

Four live stat cards (Pending, In flight, Oldest, Errors) plus a How to connect panel. The connect panel shows your project’s GraphQL endpoint with a copy button and ready-to-paste snippets, with GraphQL as the default tab and REST as the second. This is the fastest path from “queue created” to “first message flowing”.

Errors (dead-letter queue)

Messages that exhausted their attempts land here so they’re never lost. For each you can see the payload (expandable), how many times it was tried, and when it failed.

Retry all (redrive) — moves the failed messages back to the main queue to be processed again. Use this after you’ve fixed the cause. You’ll be asked to confirm, since it re-queues every error.
Empty — permanently discards the error list. This asks you to type the queue name to confirm, and tells you how many messages will be lost.

Test

Send a message by hand to confirm your worker consumes it:

Write a JSON message

Use the JSON editor. It validates as you type and enforces a 256 KB limit with a live size counter.

(Optional) Add a dedup key

A dedup key suppresses accidental duplicates: sending the same key twice within a short window enqueues the message only once.

Send

Click Send. You’ll see confirmation that the message was enqueued and the Pending count tick up.

Configuration

Change the mutable settings (processing time, max attempts, retention) and find the danger zone to delete the queue. Deleting asks you to type the queue name and warns how many messages will be discarded.

Connect your app to a queue

Everything the panel does is available through the GraphQL API, so your application code sends and processes messages the same way. The connect panel gives you copy-paste snippets; the examples below show the shape. Send a message.

mutation {
  sendMessage(
    queue: "order-processing"
    body: "{\"orderId\":\"A-1024\",\"total\":51.25}"
    # dedupKey: "order-A-1024"   # optional: suppress duplicates
  ) {
    messageId
  }
}

Receive messages (a worker pulls a batch, then confirms each once done). Receiving supports long polling — the call waits up to a few seconds for messages rather than returning empty immediately.

mutation {
  receiveMessages(queue: "order-processing", max: 10, waitSeconds: 5) {
    messages { messageId body receiptHandle }
  }
}

Confirm (delete) a processed message using the receiptHandle from the message you received:

mutation {
  deleteMessage(queue: "order-processing", receiptHandle: "…") {
    ok
  }
}

A typical worker loop is: receiveMessages → do the work → deleteMessage. If your worker crashes before deleteMessage, the message reappears after the processing time and is retried automatically.

You can also connect over REST — the connect panel’s second tab shows the equivalent curl calls. GraphQL is the recommended default because it’s the same endpoint as the rest of your project’s API.

Recover from failures

My Errors count is going up

A message is failing every attempt. Open the Errors tab, expand a payload to see what’s being processed, and check your worker’s logic and logs. Once fixed, click Retry all (redrive) to move the error list back into the main queue.

The same message seems to be processed twice

This is expected under “at least once” delivery. Make your worker idempotent (safe to run twice for the same input) — for example, key writes on the orderId so a repeat is a no-op — and use a dedup key when sending to suppress accidental duplicate sends.

Messages get retried while the worker is still running

Your job takes longer than the queue’s Processing time. Increase it on the Configuration tab, or have the worker extend the window while it processes.

Pending keeps climbing and never drains

Messages arrive faster than they’re processed. Run more workers in parallel (they compete for the same queue safely), make each job faster, or both.

Event Bus

Broadcast one event to many subscribers — including feeding one or more queues.

Using them together

Fan an event out to several queues and process each copy independently.

Home

Blueprint

Design

Frontend

Backend

Assets

The queue list

Create a queue

Settings, explained

The queue detail view

Summary

Errors (dead-letter queue)

Test

Configuration

Connect your app to a queue

Recover from failures

Next

Event Bus

Using them together

​The queue list

​Create a queue

​Settings, explained

​The queue detail view

​Summary

​Errors (dead-letter queue)

​Test

​Configuration

​Connect your app to a queue

​Recover from failures

​Next

Event Bus

Using them together

The queue list

Create a queue

Settings, explained

The queue detail view

Summary

Errors (dead-letter queue)

Test

Configuration

Connect your app to a queue

Recover from failures

Next