upstash/workflow-js / skills
upstash-workflow-js
UnverifiedLightweight guidance for using the Upstash Workflow SDK to define, trigger, and manage workflows. Use this Skill whenever a user wants to create workflow endpoints, run steps, or interact with the Upstash Workflow client.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.2 KB |
| agents.md | markdown | 6.7 KB |
| basics/client.md | markdown | 4.1 KB |
| basics/context.md | markdown | 5.1 KB |
| basics/serve.md | markdown | 2.4 KB |
| features/flow-control.md | markdown | 3.9 KB |
| features/invoke.md | markdown | 2.6 KB |
| features/retries-failures-reliability.md | markdown | 6.3 KB |
| features/wait-for-event.md | markdown | 2.8 KB |
| features/webhooks.md | markdown | 2.5 KB |
| how-to/local-dev.md | markdown | 3.2 KB |
| how-to/middleware.md | markdown | 4.7 KB |
| how-to/migrations.md | markdown | 4.8 KB |
| how-to/realtime.md | markdown | 4.8 KB |
| rest-api.md | markdown | 6.6 KB |
| troubleshooting.md | markdown | 4.8 KB |
features/retries-failures-reliability.md
View on GitHub# Workflow Reliability Features
This documentation provides a consolidated reference for reliability mechanisms in Upstash Workflow, focusing on retries, failure handling, and the Dead Letter Queue (DLQ). It is optimized for AI‑driven execution but remains clear for developers.
---
## Core Reliability Concepts
Upstash Workflow ensures that workflow runs are durable, recoverable, and traceable. Reliability is achieved through:
- Automatic retries for transient failures
- Failure handling via `failureFunction` or `failureUrl`
- DLQ for storing permanently failed runs
- Manual recovery actions: restart, resume, rerun failure function
- Mechanisms to prevent retries when failure is intentional
These mechanisms work together to guarantee that no failed execution is lost and that failures can be observed and handled.
---
## Automatic Retries
Workflow steps automatically retry when they fail, using configurable retry count and delay.
### Retry Parameters
- `retries`: How many times the step will retry
- `retryDelay`: A math expression (string) returning delay in milliseconds; can use `retried` variable
### Common Pitfalls
- The delay expression must be a _string_; raw numbers disable dynamic calculation.
- A workflow only moves to DLQ after **all** retries fail.
### Example: Configure Retry Count + Delay
```ts
import { Client, WorkflowNonRetryableError, serve } from "@upstash/workflow";
// Trigger with custom retry settings
const client = new Client({ token: process.env.WORKFLOW_TOKEN! });
await client.trigger({
url: "https://example.com/workflow",
retries: 5,
retryDelay: "(1 + retried) * 2000", // 2s, 4s, 6s...
});
// Workflow with steps that may intentionally skip retries
export const { POST } = serve(async (context) => {
const shouldFail = await context.run("check", () => true);
if (shouldFail) {
// Skips retry cycle and sends directly to failure handling
throw new WorkflowNonRetryableError("Bad state");
}
await context.run("process", () => doWork());
});
```
---
## Preventing Retries
### When to Stop Retries
Use these when failure is expected or should halt execution immediately:
- `WorkflowNonRetryableError` → Fail fast, trigger failure function, enter DLQ
- `context.cancel()` → Stop workflow intentionally, no DLQ, no failure function
- Conditional returns → Graceful early exit without error
### Pitfalls
- `context.cancel()` marks the run as **canceled**, not failed — no failure handling executes.
- Throwing any error _other than_ `WorkflowNonRetryableError` will still trigger retries.
---
## Failure Handling
You can handle workflow failures using either:
- `failureFunction` (runs in your workflow environment)
- `failureUrl` (external callback endpoint)
Only **one** can be configured — they are mutually exclusive.
### Failure Function Behavior
- Runs after all retries fail
- Receives failure metadata and workflow context
- Cannot create new workflow steps; `context` is read‑only
- Is retried if it fails
- Can be manually retried from the DLQ
### Failure Function Parameters
- `context.workflowRunId`
- `context.url`
- `context.requestPayload`
- `context.headers`
- `context.env`
- `failStatus`
- `failResponse`
- `failHeaders`
### Example: Workflow + Failure Function + Prevent‑Retry Logic
```ts
export const { POST } = serve(
async (context) => {
const ok = await context.run("verify", () => verifySomething());
if (!ok) {
throw new WorkflowNonRetryableError("Verification failed");
}
const shouldAbort = await context.run("check", () => false);
if (shouldAbort) {
await context.cancel();
return;
}
await context.run("execute", () => doWork());
},
{
failureFunction: async ({ context, failStatus, failResponse }) => {
// Logging / cleanup / alerts
await logFailure(context.workflowRunId, failStatus, failResponse);
},
}
);
```
---
## Dead Letter Queue (DLQ)
A workflow enters the DLQ when:
- A step fails _after all retries_
- A `WorkflowNonRetryableError` is thrown
- `failureFunction` also fails (visible as failed in DLQ)
### Retention
- Free: 3 days
- Pay‑as‑you‑go: 1 week
- Fixed: Up to 3 months
After retention expires, items cannot be recovered.
---
## DLQ Recovery Actions
You may perform these actions from the dashboard or programmatically.
### 1. Resume
Continue from the failed step while keeping previous step results.
### 2. Restart
Start the entire workflow from scratch, discarding previous results.
### 3. Rerun Failure Function
Retry the failure handler **only if it previously failed**.
### Example: All DLQ Actions
```ts
import { Client } from "@upstash/workflow";
const client = new Client({ token: process.env.WORKFLOW_TOKEN! });
await client.dlq.resume({ dlqId: "dlq-1", retries: 3 }); // Continue run
await client.dlq.restart({ dlqId: "dlq-2", retries: 3 }); // Restart
await client.dlq.retryFailureFunction({ dlqId: "dlq-3" }); // Retry failure handler
```
### Pitfalls
- `retryFailureFunction` is only allowed when the failure function failed.
- `resume` cannot be used if workflow code changed before the failure point.
- `restart` re-executes everything, including expensive steps.
---
## Failure URL (Advanced Option)
Use when failure must be handled by a separate service.
### Notes
- Use **either** `failureFunction` **or** `failureUrl`.
- Recommended only when your primary app might be offline.
- Failure URL receives a structured JSON payload about the failed request.
### Example
```ts
export const { POST } = serve(
async (context) => {
await context.run("work", () => doWork());
},
{
failureUrl: "https://example.com/failure-handler",
}
);
```
---
## Debugging Failed Runs
DLQ entries store:
- Request + response headers
- Payloads
- Failure metadata
- Failure function state
Use the dashboard filters (workflow run ID, URL, failure function state) to identify and debug root causes.
---
## Summary
This skill unifies all Workflow reliability controls:
- Retries (automatic, configurable)
- Failure handling (`failureFunction`, `failureUrl`)
- DLQ retention + recovery
- Fast‑fail mechanisms (`WorkflowNonRetryableError`, `cancel`, conditional exits)
- Manual recovery operations (resume, restart, retry failure function)
Together these features ensure workflows are resilient, debuggable, and recoverable under all failure scenarios.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |