Forge Workflows (@forge/workflows) is under development and is not yet available. These pages describe the
planned API, which may change before release.
For more details, see Forge EAP, Preview, and GA.
A workflow is a chain of steps that runs in the background as a run. Each task call in the chain runs in its own invocation. For an introduction, see Forge Workflows API.
A step is retried when it throws one of these errors:
RetryableError, or any error with retryable: truestatus or statusCode of 429 or 5xx, such as a rate limit from the Forge LLMs APIRateLimitError or InternalServerError from a Forge SDKtimeoutSeconds
optionProduct API calls such as requestJira return a response instead of throwing. To have a failed call retried, check
the response, and throw an error with its status, or a RetryableError.
By default, a step gets 3 attempts in total. The first retry waits 2 seconds, and the wait doubles each time, up to
900 seconds. To change this for a task, use its
retry option. To retry every error, set
retryAll: true.
Other errors fail the step straight away. The run then continues at the next
.catch(). If there isn't one, the run fails,
and runs.get returns the error.
When a run fails because of the workflow itself, the error has one of these codes. A .catch() handler receives
the same code.
| Code | Meaning |
|---|---|
LOOP_LIMIT | A loop didn't return done() within maxIterations. |
LOOP_BODY_RESULT | A loop body returned something other than next(state) or done(value). |
LOOP_SIGNAL | A loop body called waitForSignal(), which you can't use inside a loop. Wait for the signal before the loop. |
SIGNAL_TIMEOUT | No signal arrived within waitForSignal()'s timeoutSeconds. Without timeoutSeconds, a wait has no timeout. |
SIGNAL_IN_USE | Two steps of the same run waited for the same signal name at once, for example in a fan-out. |
STEP_TIMEOUT | An attempt took longer than the task's timeoutSeconds. The attempt is retried, so the run fails with this code only if the last attempt times out. |
FUTURE_IN_VALUE | A step's value held a future, for example inside an array, where it would never run. The build catches most of these. |
VALUE_TOO_LARGE | A step's value, or the combined results of a collect(), is larger than 240 KB. This is never retried. |
PUSH_LIMIT | The run used up its budget of about 1,000 queue pushes. Split the work into several runs. |
CHILD_DEPTH | Sub-workflows called each other more than 10 deep, for example because a sub-workflow calls itself. |
CHILD_CANCELLED | A sub-workflow was cancelled before it finished. |
WORKFLOW_VERSION_GONE, HANDLER_MISSING | The app was redeployed with a changed workflow while this run was in progress. See Redeploying. |
CAPTURES_MISSING, JOIN_STATE_MISSING | The run's saved state is missing, for example because it expired. Start a new run. |
A step can occasionally run twice, because Forge delivers async events at least once, and because an invocation can be interrupted. Make side effects safe to repeat. For example, check whether a comment already exists before you post it, or use an operation that has the same effect when repeated, such as adding a label.
Starting a workflow twice starts two runs. If the code that starts a run can be called twice, such as a retried trigger or a double-clicked button, check for an existing run first. For example, save the run ID in app storage and look it up before you start another run.
When you redeploy, runs that are in progress carry on with your new code, as long as the workflow's chain hasn't changed:
WORKFLOW_VERSION_GONE. This includes adding, removing or
reordering steps, changing the code in a step written inline in the chain, changing maxIterations, and renaming
the workflow's function or moving it to another file. Reformatting the code or changing comments doesn't count.
A sub-workflow is a workflow of its own: if you change its chain, its runs in progress fail with this code, and so
do the steps that called them.Runs of workflows you didn't change carry on as normal. To change a chain without failing runs in progress, add a new workflow function, and start new runs with it.
| Limit | Value |
|---|---|
| Value size | 240 KB for each value passed between steps, including the combined results of a collect(). Values must be plain JSON data. |
| Step duration | 900 seconds, the function timeout. |
| Waits | 7 days for each sleep(), and for waitForSignal()'s timeoutSeconds. A waitForSignal() without a timeout can wait until the run's state expires, 14 days after the run starts. |
| Queue pushes | About 1,000 per run, an async events limit. Each step, retry and loop iteration uses one, and so does every 15 minutes of a sleep() or a signal timeout. A run that reaches the limit fails with code PUSH_LIMIT. |
| Run status | Kept for 14 days after the run finishes. |
| Loop iterations | 25 by default. Set maxIterations to change it. |
| Sub-workflow depth | 10. A run's sub-workflows share its queue pushes. |
| Fan-out concurrency | 10 at once by default, and at most 25. |
Workflows count toward your app's async events limits and storage limits. For jobs of many thousands of items, split the work into several runs.
asApp(). A step
can do anything your app can, so before you start a run, check that the user is allowed to do what it does.runs acts on any run in your app. Before you call runs.get, runs.cancel or runs.signal, check that the
caller is allowed to act on that run. For example, look up the run ID from data the user can access, instead of
accepting a run ID from the frontend.You can't run a workflow in your app's unit tests yet. If a test calls a workflow function, it throws an error. Instead, test the functions that your tasks wrap as ordinary functions.
To test a whole workflow, deploy your app to a development environment, start a run, and call
runs.get until it finishes.
To list the workflows that the Forge CLI finds in your app, run:
1 2npx forge-workflows inspect
If a workflow function throws an error saying that the chain must be compiled with the Forge CLI, the CLI didn't
recognise the chain. Check that it's in a .ts file, that its values have types (not any), and that it follows
the rules.
Rate this page: