> ## Documentation Index
> Fetch the complete documentation index at: https://archie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Queues
> Create a queue, send messages to it, and have workers process them one at a time in the background. Tune retries and timing in plain language, watch live health, and recover failed jobs from the error list.
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.
In the Queues panel, click **New queue**.
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.
The **Configuration (recommended defaults)** section is pre-filled with sensible values. Change them only if you need to — see the table below.
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:
Use the JSON editor. It validates as you type and enforces a 256 KB limit with a live size counter.
A **dedup key** suppresses accidental duplicates: sending the same key twice within a short window enqueues the message only once.
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.**
```graphql theme={null}
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.
```graphql theme={null}
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:
```graphql theme={null}
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
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.
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.
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.
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.
## Next
Broadcast one event to many subscribers — including feeding one or more queues.
Fan an event out to several queues and process each copy independently.