Developer
News and Updates
Get Support
Sign in
Get Support
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Sign in
DOCUMENTATION
Cloud
Data Center
Resources
Sign in
Runtimes
Web triggers
Async events
Workflows
Realtime events
Dynamic Modules
Customer-managed egress and remotes
License API
Installation Details API
Atlassian app REST APIs
Fetch APIs
LLMs API
Last updated Nov 11, 2026

Forge Workflows errors, limits and testing

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.

Retries

A step is retried when it throws one of these errors:

  • a RetryableError, or any error with retryable: true
  • an error with an HTTP status or statusCode of 429 or 5xx, such as a rate limit from the Forge LLMs API
  • a RateLimitError or InternalServerError from a Forge SDK
  • a timeout from the task's timeoutSeconds option

Product 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.

Error codes

When a run fails because of the workflow itself, the error has one of these codes. A .catch() handler receives the same code.

CodeMeaning
LOOP_LIMITA loop didn't return done() within maxIterations.
LOOP_BODY_RESULTA loop body returned something other than next(state) or done(value).
LOOP_SIGNALA loop body called waitForSignal(), which you can't use inside a loop. Wait for the signal before the loop.
SIGNAL_TIMEOUTNo signal arrived within waitForSignal()'s timeoutSeconds. Without timeoutSeconds, a wait has no timeout.
SIGNAL_IN_USETwo steps of the same run waited for the same signal name at once, for example in a fan-out.
STEP_TIMEOUTAn 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_VALUEA step's value held a future, for example inside an array, where it would never run. The build catches most of these.
VALUE_TOO_LARGEA step's value, or the combined results of a collect(), is larger than 240 KB. This is never retried.
PUSH_LIMITThe run used up its budget of about 1,000 queue pushes. Split the work into several runs.
CHILD_DEPTHSub-workflows called each other more than 10 deep, for example because a sub-workflow calls itself.
CHILD_CANCELLEDA sub-workflow was cancelled before it finished.
WORKFLOW_VERSION_GONE, HANDLER_MISSINGThe app was redeployed with a changed workflow while this run was in progress. See Redeploying.
CAPTURES_MISSING, JOIN_STATE_MISSINGThe run's saved state is missing, for example because it expired. Start a new run.

Running twice

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.

Redeploying

When you redeploy, runs that are in progress carry on with your new code, as long as the workflow's chain hasn't changed:

  • You can change the code inside a task. Runs in progress use the new code for their remaining steps.
  • Changing the chain fails runs in progress with code 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.

Limits

LimitValue
Value size240 KB for each value passed between steps, including the combined results of a collect(). Values must be plain JSON data.
Step duration900 seconds, the function timeout.
Waits7 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 pushesAbout 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 statusKept for 14 days after the run finishes.
Loop iterations25 by default. Set maxIterations to change it.
Sub-workflow depth10. A run's sub-workflows share its queue pushes.
Fan-out concurrency10 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.

Security

  • Steps run with the app's permissions, and have no user context. Call Atlassian APIs with 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.
  • Don't capture secrets. Values that a step uses from the workflow's function are saved for the life of the run. Don't use tokens or other secrets this way. Read them inside the task instead.
  • Don't log step values. They often contain issue content and model output. Error messages from failed steps appear in your app's logs.

Testing

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
2
npx 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: