# Error codes

<!-- Generated by tools/errors/generate.py from flow.service.workflow 5.0.0-beta.39. Don't edit by hand; edit tools/errors/notes.json. -->

# Error codes

When Flow refuses a request, the API answers with a code, a reason and a message. When a task or run ends early, it carries a status reason. This page lists them all, as Flow 5.0.0-beta.39 defines them, with what each means and what to do.

To find one, search this page for the code or the reason, such as `1020` or `QUOTA_EXCEEDED`. Status reasons, such as `ParamUnresolved`, are under [Task and run status reasons](#task-and-run-status-reasons).

## How to read an entry

- **The heading** is the error's reason, as the response's `reason` field carries it. Look errors up by reason, not code: a few codes carry two reasons.
- **The HTTP status and code** are the response's status and its `code` field.
- **The message** is the response's `message`, verbatim. `{…}` marks a value Flow fills in, such as a name or a count.
- **Not returned in this release** marks a code Flow defines but never sends.

For the whole response body, see [Read an error](https://www.useboomerang.io/docs/flow/main/apis/overview#read-an-error).

## Workflows

Errors from creating, saving, reading and submitting a workflow. Codes 400, 423, 429, 1201–1202, 1204–1208, 1211–1215, 1218–1223.

### WORKFLOW_INVALID_REFERENCE

HTTP status 404 · code 1201

```text
Invalid Workflow reference has been provided.
```

**Why it happens:** No workflow with that name or ID is in the workspace, or you can't reach it. Flow answers the same way for both, so the answer doesn't reveal a workflow you can't see. A webhook or event whose `ref` names no workflow the token can reach gets this answer too.

**What to do:** Check the workflow's name, which is its slug, such as `deploy-service`, and the workspace the request names. For a webhook or event, check that the token can reach that workspace.

**Related:** [Triggers: Webhook](https://www.useboomerang.io/docs/flow/main/fundamentals/triggers#webhook), [A webhook or event didn't start a run](https://www.useboomerang.io/docs/flow/main/introduction/troubleshooting#a-webhook-or-event-didnt-start-a-run)

### WORKFLOW_NOT_ACTIVE

HTTP status 400 · code 1202

```text
The Workflow specified is not currently active and cannot be run.
```

**Why it happens:** The workflow's status is `inactive`, so Flow won't run it. The status icon on its card shows **Inactive**.

**What to do:** Set the workflow's `status` back to `active` with `PUT /api/v2/workspace/{workspace}/workflow`. The webapp doesn't change a workflow's status.

**Related:** [What a card shows](https://www.useboomerang.io/docs/flow/main/fundamentals/workflows#what-a-card-shows), [Update a workflow](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute#update-replace-or-create-new-workflow)

### WORKFLOW_REVISION_NOT_FOUND

HTTP status 409 · code 1204

```text
No valid Workflow Revisions found.
```

See: [Workflow editor](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor).

### WORKFLOW_NON_UNIQUE_TASK_NAME

HTTP status 400 · code 1205

```text
Non unique task name has been provided. All tasks must have unique names.
```

**Why it happens:** Two nodes in the workflow have the same **Task name**. Flow uses the name to tell nodes apart, as in `$(tasks.<name>.results.<result>)`.

**What to do:** Give each node its own **Task name**, then save.

**Related:** [Configure a task](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor#configure-a-task)

### WORKFLOW_INVALID_TASK_REF

HTTP status 400 · code 1206

```text
Invalid Task reference provided. Task name: {…}, Task reference: {…}.
```

**Why it happens:** A node uses a task that isn't in the workspace or the catalogue, such as one deleted since the node was added. For a **Run Workflow** node, the workflow it names isn't in the workspace. The message names the node and the reference.

**What to do:** Replace the node with a task from the palette, or choose a workflow that exists, then save.

**Related:** [Add a task](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor#add-a-task)

### WORKFLOW_INVALID_TASK_PARAM

HTTP status 400 · code 1208

```text
Undeclared parameter(s) provided for a Task. Task name: {…}, Undeclared parameter(s): {…}.
```

**Why it happens:** A node sets a parameter its task version doesn't declare. The message names the node and the undeclared parameters. Flow matches names ignoring case.

**What to do:** Remove the parameter from the node, or move the node to a task version that declares it.

**Related:** [Update a task to its latest version](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor#update-a-task-to-its-latest-version)

### WORKFLOW_MISSING_TASK_REF

HTTP status 400 · code 1211

```text
Task "{…}" has no task reference.
```

**Why it happens:** A node names no task: its `taskRef` is blank. This comes from a workflow written through the API or imported, not from the editor.

**What to do:** Set `taskRef` on the node, or delete the node and add the task again from the palette.

**Related:** [Workflow editor](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor)

### WORKFLOW_INVALID_REQ

HTTP status 400 · code 1212

```text
Invalid Workflow request has been provided.
```

**Why it happens:** Part of the request is blank, missing or out of range. Common causes: a new workflow with no name, or with the name of a workflow the workspace already has; a **Concurrency limit** below 1; a task's **Retries** outside 0 to 10, or a retry wait below 1 second; a CloudEvent Flow can't read, or one without a `ref` whose `subject` names no workflow.

**What to do:** Correct the field. The message doesn't name it, so compare the request with the route in the API reference.

**Related:** [Configure a workflow](https://www.useboomerang.io/docs/flow/main/guides/configure-workflow#set-the-timeout-retries-and-concurrency), [Workflows API](https://www.useboomerang.io/docs/flow/main/apis/WorkflowsRoute)

### WORKFLOW_INVALID_TASK_FOREACH

HTTP status 400 · code 1213

```text
Invalid for-each setting on a Task. Task name: {…}. {…}
```

**Why it happens:** A node's for-each setting can't run. The message ends with the cause: the task type can't repeat per item; the items aren't a JSON array or one reference such as `$(params.items)`; a typed array has more entries than **Maximum For-Each Items**, 256 by default; or the task declares a parameter named `item` or `index`, which Flow gives each item.

**What to do:** Fix what the message names, then save.

**Related:** [Repeat a task for each item: Limits](https://www.useboomerang.io/docs/flow/main/guides/repeat-a-task-for-each-item#limits)

### WORKFLOW_INVALID_TASK_NAME

HTTP status 400 · code 1214

```text
Task names cannot end in "[" followed by digits and "]"; that form is reserved for for-each items. Task name: {…}.
```

**Why it happens:** A node's name ends in `[`, digits and `]`, such as `deploy[2]`. Flow names each for-each item that way, so the form is reserved.

**What to do:** Rename the node. Other brackets, such as `Deploy [prod]`, are allowed.

**Related:** [Repeat a task for each item](https://www.useboomerang.io/docs/flow/main/guides/repeat-a-task-for-each-item)

### WORKFLOW_STORAGE_REMOVED

HTTP status 422 · code 1215

```text
This workflow was upgraded with Workflow storage, which Flow 5 no longer provides. Save the workflow again to clear this; to keep files between runs, use Upload Artifact and Download Artifact with scope "workflow".
```

**Why it happens:** The workflow came from Flow 3 with Workflow storage on, and hasn't been saved since. Flow 5 has no Workflow storage, so it won't run the workflow until you save it.

**What to do:** Open the workflow in the editor and save a new version. To keep files between runs, use **Upload Artifact** and **Download Artifact** with the scope `workflow`.

**Related:** [Keep files between runs](https://www.useboomerang.io/docs/flow/main/guides/keep-files-between-runs), [Upgrade from v3: Update workflows](https://www.useboomerang.io/docs/flow/main/hosting/upgrading#update-workflows)

### WORKFLOW_INVALID_CHILD_PARAM

HTTP status 400 · code 1218

```text
Parameter(s) not declared by the child workflow. Task name: {…}, Child workflow: {…}, Undeclared parameter(s): {…}.
```

**Why it happens:** A **Run Workflow** node passes a parameter the child workflow doesn't declare. The message names the node, the child workflow and the parameters.

**What to do:** Declare the parameter on the child workflow and save it, or remove it from the node.

**Related:** [Child workflows](https://www.useboomerang.io/docs/flow/main/fundamentals/runs#child-workflows)

### WORKFLOW_TEMPLATE_SYSTEM_ONLY

HTTP status 400 · code 1219

```text
A workflow of type "{…}" can only be created in the system workspace.
```

See: [Templates](https://www.useboomerang.io/docs/flow/main/fundamentals/workflows#templates).

### WORKFLOW_TEMPLATE_INVALID_REF

HTTP status 400 · code 1220

```text
Invalid template reference: no template named "{…}" (version {…}) exists in the system workspace.
```

See: [Templates](https://www.useboomerang.io/docs/flow/main/fundamentals/workflows#templates).

### WORKFLOW_TEMPLATE_IN_USE

HTTP status 409 · code 1221

```text
The template cannot be deleted while workflows run it by reference. Remove or re-point those workflows first.
```

See: [Templates](https://www.useboomerang.io/docs/flow/main/fundamentals/workflows#templates).

### WORKFLOW_INVALID_FINALLY

HTTP status 400 · code 1222

```text
Invalid finally task. Task name: {…}. {…}
```

**Why it happens:** A finally task is linked wrongly. A finally task has exactly one link, from the end, and nothing may depend on it. The message names the task and the rule it breaks.

**What to do:** Link the finally task from the end only, and remove any link that leaves it.

**Related:** [Run a task after the run ends](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor#run-a-task-after-the-run-ends)

### WORKFLOW_INVALID_TASK_RETRY

HTTP status 400 · code 1223

```text
Invalid retry setting on a Task. Task name: {…}. {…}
```

**Why it happens:** A node asks for retries, but its type is never retried. Only tasks that run as a container retry: catalogue and workspace tasks, script tasks, **Run Custom Task**, the AI tasks and the artifact tasks. A **Run Workflow** node's retries belong on the tasks of the workflow it runs.

**What to do:** Set **Retries** on that node to 0, or leave it blank.

**Related:** [Let a task retry its own failures](https://www.useboomerang.io/docs/flow/main/guides/retry-a-run#let-a-task-retry-its-own-failures)

### IMPORT_WORKFLOW_FAILED

HTTP status 400 · code 400

```text
Workflow not imported - template(s) not found
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Workflow editor](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor).

### WORKFLOW_WORKSPACE_INACTIVE

HTTP status 423 · code 423

```text
The workspace this workflow is associated with is no longer active.
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Workflow editor](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor).

### WORKFLOW_TRIGGER_DISABLED

HTTP status 429 · code 429, shared with `TOO_MANY_REQUESTS`

```text
The required workflow trigger has not been enabled.
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Workflow editor](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor).

### WORKFLOW_DELETE_IN_FLIGHT_RUNS

HTTP status 409 · code 1207

```text
Workflow cannot be deleted while it has in-flight WorkflowRuns. Cancel or wait for the running executions to finish first.
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Workflow editor](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor).

## Runs

Errors from starting, retrying and reading runs, and from the actions, schedules and artifacts that belong to a run. Codes 1301–1307, 1601–1603, 1701–1705, 2001–2008.

### WORKFLOWRUN_INVALID_REFERENCE

HTTP status 404 · code 1301

```text
Invalid WorkflowRun reference has been provided.
```

**Why it happens:** No run with that ID exists, or you can't reach it. A callback whose `ref` names no run gets this too. Flow deletes finished runs after **Activity Retention (days)**, 365 days by default.

**What to do:** Check the run ID. For a callback, send the ID from `$(context.params.workflowrun-ref)`.

**Related:** [Resume a waiting run with a callback](https://www.useboomerang.io/docs/flow/main/fundamentals/triggers#resume-a-waiting-run-with-a-callback), [How long runs are kept](https://www.useboomerang.io/docs/flow/main/fundamentals/runs#how-long-runs-are-kept)

### WORKFLOWRUN_INVALID_REQUIREMENT

HTTP status 400 · code 1302

```text
Invalid WorkflowRun request has been provided.
```

See: [Runs](https://www.useboomerang.io/docs/flow/main/fundamentals/runs).

### WORKFLOWRUN_INVALID_DEPENDENCY

HTTP status 400 · code 1303

```text
Invalid WorkflowRun request. Task Dependency Reference not found: {…}.
```

See: [Runs](https://www.useboomerang.io/docs/flow/main/fundamentals/runs).

### WORKFLOWRUN_INVALID_PHASE

HTTP status 400 · code 1304

```text
Invalid WorkflowRun request. WorkflowRun is not in the correct phase. Current: {…}, Needed: {…}.
```

**Why it happens:** A start request names a run that isn't waiting to start: it's already running or completed, or it's parked for a slot under its workflow's concurrency limit.

**What to do:** Start only a run submitted with `start=false`. A parked run starts on its own when a slot frees.

**Related:** [Limit how many runs overlap](https://www.useboomerang.io/docs/flow/main/fundamentals/runs#limit-how-many-runs-overlap)

### WORKFLOWRUN_TRIGGER_DISABLED

HTTP status 400 · code 1305

```text
The Trigger provided is not enabled for this Workflow.
```

**Why it happens:** The run came through a trigger that's off for this workflow: **Manual**, **Scheduler**, **Webhook**, **Events** or **GitHub**. An event or GitHub delivery also gets this answer when one of the trigger's filters doesn't match. The workflow card shows **Trigger disabled** when **Manual** is off.

**What to do:** Turn the trigger on under **Configure › Triggers**, then select **Create new version**. For **Events**, check each filter row: an **in** row never matches at this release.

**Related:** [Triggers](https://www.useboomerang.io/docs/flow/main/fundamentals/triggers), [The Events trigger's in operation never matches](https://www.useboomerang.io/docs/flow/main/introduction/known-issues#the-events-triggers-in-operation-never-matches)

### WORKFLOWRUN_TIMEOUT_TOO_SHORT

HTTP status 400 · code 1306

```text
Invalid WorkflowRun request. The {…} of {…} minutes is shorter than the {…} minutes required by the longest chain of task timeouts.
```

**Why it happens:** The run's timeout is shorter than the longest chain of task timeouts through the graph, so Flow refuses the run rather than let it time out partway. The message names where the timeout came from: the requested run timeout, the workflow's, the default, or the workspace maximum run duration that caps them. A waiting task's own timeout doesn't count toward the chain.

**What to do:** Raise **Timeout** under **Configure › Run Options**, or lower the task timeouts on the longest path. If the message names the workspace maximum run duration, ask an admin to raise the **Run Duration** quota.

**Related:** [Runs: Timeouts](https://www.useboomerang.io/docs/flow/main/fundamentals/runs#timeouts)

### WORKFLOWRUN_RETRY_INVALID

HTTP status 400 · code 1307

```text
Invalid retry request. {…}
```

**Why it happens:** Flow can't build the retry you asked for, and the message ends with why: the run's workflow version no longer exists; a chosen task isn't in the workflow, or is its start or end; a chosen task sits between an **Acquire Lock** and its **Release Lock**; or you asked to retry the failed tasks of a run where none failed.

**What to do:** Fix what the message names. To run a newer version of the workflow, start a new run with **Run it**.

**Related:** [Know what a retry keeps](https://www.useboomerang.io/docs/flow/main/guides/retry-a-run#know-what-a-retry-keeps)

### ACTION_INVALID_REF

HTTP status 404 · code 1601

```text
Invalid Action reference has been provided.
```

See: [Actions](https://www.useboomerang.io/docs/flow/main/fundamentals/actions).

### ACTION_INVALID_APPROVERGROUP

HTTP status 400 · code 1602

```text
Member not a part of a valid Approver Group.
```

**Why it happens:** The approval names an approver group that isn't in the workspace the request went through, or that no longer exists. A decision from someone outside the group isn't refused with this code: Flow doesn't record it.

**What to do:** Answer the approval from the workspace that owns its run. To decide an approval that names a group, you must be a member: ask an owner or editor to add you under **Manage workspace › Approver Groups**.

**Related:** [Actions: Who can answer](https://www.useboomerang.io/docs/flow/main/fundamentals/actions#who-can-answer)

### ACTION_UNABLE_TO_ACTION

HTTP status 400 · code 1603

```text
Unable to process the associated TaskRun for this Action.
```

**Why it happens:** Flow couldn't record the decision. The action already has every decision it needs, for example from another approver at the same moment, or the task behind it couldn't be ended, for example because its run already ended.

**What to do:** Reload **Actions**: the action has probably been decided. When a run ends first, its open actions close with it.

**Related:** [When the run ends first](https://www.useboomerang.io/docs/flow/main/fundamentals/actions#when-the-run-ends-first)

### SCHEDULE_INVALID_REF

HTTP status 404 · code 1701

```text
Invalid Schedule reference has been provided.
```

See: [Schedules](https://www.useboomerang.io/docs/flow/main/webapp/schedules).

### SCHEDULE_INVALID_REQ

HTTP status 400 · code 1702

```text
Invalid Schedule request. Required fields have not been provided.
```

**Why it happens:** The schedule is missing a required field: a run-once schedule needs a date, a repeating one a cron expression, and every schedule a time zone. Flow answers the same when the workflow the schedule names isn't in the workspace.

**What to do:** Fill in the missing field, or choose a workflow in this workspace.

**Related:** [Create a schedule](https://www.useboomerang.io/docs/flow/main/webapp/schedules#create-a-schedule)

### SCHEDULE_INVALID_RUNONCE

HTTP status 400 · code 1703

```text
Cannot enable schedule as it is in the past.
```

**Why it happens:** You enabled a run-once schedule whose time has passed. Flow sets the schedule's status to error.

**What to do:** Edit the schedule to a future date and time, then enable it.

**Related:** [Manage schedules](https://www.useboomerang.io/docs/flow/main/webapp/schedules#manage-schedules)

### ARTIFACT_INVALID_REF

HTTP status 404 · code 2001

```text
No artifact "{…}" was found on this run.
```

**Why it happens:** No artifact of that name is in the scope the task asks for: this run, for scope `run`, or an earlier run of the workflow, for scope `workflow`. **Download Artifact** then fails with the reason `ArtifactRefused` and this message, unless **Optional** is on.

**What to do:** Check that **Artifact name** and **Scope** match the upload. For a download a first run won't find, turn on **Optional**: the task then succeeds with `found` set to `false`.

**Related:** [Artifacts](https://www.useboomerang.io/docs/flow/main/fundamentals/artifacts#artifacts)

### ARTIFACT_INVALID_NAME

HTTP status 400 · code 2002

```text
Artifact name "{…}" is invalid. Names may contain letters, digits, ".", "-" and "_", start with a letter or digit, and be at most 128 characters.
```

**Why it happens:** **Upload Artifact**'s **Artifact name** breaks the naming rule: letters, digits, `.`, `-` and `_`, starting with a letter or digit, up to 128 characters. The task fails with the reason `ArtifactRefused`.

**What to do:** Change **Artifact name** to fit the rule.

**Related:** [Artifacts](https://www.useboomerang.io/docs/flow/main/fundamentals/artifacts#artifacts)

### ARTIFACT_ALREADY_EXISTS

HTTP status 409 · code 2003

```text
This run already has an artifact named "{…}". Artifact names are unique within a run.
```

**Why it happens:** An earlier upload in this run used the same name. Names are unique within a run, whatever their scope. The task fails with the reason `ArtifactRefused`.

**What to do:** Give each **Upload Artifact** in the workflow its own **Artifact name**.

**Related:** [Artifacts](https://www.useboomerang.io/docs/flow/main/fundamentals/artifacts#artifacts)

### ARTIFACT_TOO_LARGE

HTTP status 413 · code 2004

```text
Artifact "{…}" is {…} bytes; the largest artifact allowed is {…} bytes.
```

**Why it happens:** The uploaded file is larger than **Admin › Settings › Artifacts › Largest Artifact (MB)**, 1,024 MB by default. Flow deletes the file and fails the task with the reason `ArtifactRefused`.

**What to do:** Upload less, such as a compressed archive of only what later tasks need, or ask an admin to raise **Largest Artifact (MB)**.

**Related:** [Artifacts: Limits](https://www.useboomerang.io/docs/flow/main/fundamentals/artifacts#limits)

### ARTIFACT_EXPIRED

HTTP status 410 · code 2005

```text
Artifact "{…}" expired on {…} and its file has been deleted.
```

**Why it happens:** The artifact's retention ran out, and Flow deleted its file. When the message says it expired on `replacement`, a newer upload of the same workflow-scoped artifact replaced it.

**What to do:** Upload the file again. To keep a run-scoped artifact longer, set **Retention days** on **Upload Artifact**, up to **Maximum Retention (days)**.

**Related:** [How long is an artifact kept?](https://www.useboomerang.io/docs/flow/main/fundamentals/artifacts#how-long-is-an-artifact-kept)

### ARTIFACT_NOT_UPLOADED

HTTP status 400 · code 2006

```text
Artifact "{…}" has no uploaded file to complete.
```

See: [Artifacts and the run workspace](https://www.useboomerang.io/docs/flow/main/fundamentals/artifacts).

### ARTIFACTS_NOT_CONFIGURED

HTTP status 503 · code 2007

```text
Artifacts are not configured on this instance: set flow.artifacts.enabled and the artifact store properties.
```

**Why it happens:** This install has no artifact store, so Flow can't keep artifacts or stored task logs.

**What to do:** Ask your operator to connect one: `flow.artifacts.enabled` and the artifact store properties on service-core.

**Related:** [Connect the artifact store](https://www.useboomerang.io/docs/flow/main/hosting/configuring#connect-the-artifact-store)

### ARTIFACT_INVALID_SCOPE

HTTP status 400 · code 2008

```text
Artifact "{…}" has an invalid scope setting. {…}
```

See: [Artifacts and the run workspace](https://www.useboomerang.io/docs/flow/main/fundamentals/artifacts).

### SCHEDULE_INVALID_CRON

HTTP status 400 · code 1704

```text
Invalid Cron expression provided. Please validate the cron expression.
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Schedules](https://www.useboomerang.io/docs/flow/main/webapp/schedules).

### SCHEDULE_ERROR

HTTP status 400 · code 1705

```text
Error creating schedule. Please validate the request and try again. Error: {…}
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Schedules](https://www.useboomerang.io/docs/flow/main/webapp/schedules).

## Tasks

Errors from Task Manager and the task routes, and from the dispatcher protocol. Codes 1401–1406, 1501–1508, 2101–2102.

### TASK_INVALID_REFERENCE

HTTP status 404 · code 1401

```text
Invalid Task reference provided: {…} @ {…}
```

**Why it happens:** No task of that name and version is in the workspace or the catalogue. The message shows the name, which is the task's slug, and the version, or `latest`. A node pinned to a version that doesn't exist gets this when the workflow is saved.

**What to do:** Check the task's name and versions in Task Manager, or update the node to the task's latest version.

**Related:** [Update a task to its latest version](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor#update-a-task-to-its-latest-version)

### TASK_ALREADY_EXISTS

HTTP status 400 · code 1402

```text
A Task already exists with name: {…}
```

**Why it happens:** A task with that name is already in the workspace, or in the catalogue for a global task. A task's name is its slug, so it can't repeat.

**What to do:** Choose another **Name**, or save a new version of the existing task instead.

**Related:** [Add the task in Task Manager](https://www.useboomerang.io/docs/flow/main/guides/tasks#add-the-task-in-task-manager)

### TASK_INVALID_NAME

HTTP status 400 · code 1403

```text
Task names can only contain alphanumeric and - characters (case-insensitive). Supplied: {…}.
```

**Why it happens:** The task's **Name** is blank, or has a character other than letters, digits and `-`.

**What to do:** Use letters, digits and hyphens only, such as `send-report`.

**Related:** [Add the task in Task Manager](https://www.useboomerang.io/docs/flow/main/guides/tasks#add-the-task-in-task-manager)

### TASK_INACTIVE_STATUS

HTTP status 400 · code 1404

```text
Task reference has inactive status. Tasks must be enabled (active status). Supplied: {…} @ {…}.
```

**Why it happens:** The task is archived. Flow refuses to save a workflow with a node that uses it, and to start a run of one. Updating an archived task gets this too, unless the update restores it.

**What to do:** Select **Restore** on the task in Task Manager, or replace the node with an active task.

**Related:** [Change a task that workflows use](https://www.useboomerang.io/docs/flow/main/guides/tasks#change-a-task-that-workflows-use)

### TASK_DELETE_IN_USE

HTTP status 409 · code 1405, shared with `TASK_INVALID_WORKFLOWREF`

```text
Task cannot be deleted while in-flight TaskRuns reference it. Cancel or wait for the running executions to finish first.
```

**Why it happens:** A task run that uses the task is still pending, queued or running. Flow refuses the delete so that run doesn't lose the task's definition.

**What to do:** Wait for those runs to end, or cancel them, then delete again. The webapp doesn't delete tasks: **Archive** retires one.

**Related:** [Change a task that workflows use](https://www.useboomerang.io/docs/flow/main/guides/tasks#change-a-task-that-workflows-use)

### TASK_INVALID_REQ

HTTP status 400 · code 1406

```text
Invalid Task request has been provided.
```

See: [Tasks](https://www.useboomerang.io/docs/flow/main/fundamentals/tasks).

### TASKRUN_INVALID_REFERENCE

HTTP status 404 · code 1501

```text
Invalid TaskRun reference has been provided.
```

See: [Dispatcher protocol reference](https://www.useboomerang.io/docs/flow/main/extend/dispatcher-protocol#start-and-end-a-task).

### TASKRUN_INVALID_REQUIREMENT

HTTP status 400 · code 1502

```text
Invalid TaskRun request has been provided.
```

See: [Dispatcher protocol reference](https://www.useboomerang.io/docs/flow/main/extend/dispatcher-protocol#start-and-end-a-task).

### TASKRUN_INVALID_TYPE

HTTP status 400 · code 1504

```text
The task type from referenced template is invalid. Type provided: {…}
```

See: [Dispatcher protocol reference](https://www.useboomerang.io/docs/flow/main/extend/dispatcher-protocol#start-and-end-a-task).

### TASKRUN_INVALID_END_STATUS

HTTP status 400 · code 1505

```text
Invalid Status provided as part of a TaskRun end request. Allowed Status: 'succeeded', 'failed', 'invalid'.
```

**Why it happens:** A dispatcher ended a task with a `status` other than `succeeded`, `failed` or `invalid`. An absent `status` means `succeeded`.

**What to do:** Send one of the three.

**Related:** [Dispatcher protocol reference: The end](https://www.useboomerang.io/docs/flow/main/extend/dispatcher-protocol#the-end)

### TASKRUN_CLAIM_SUPERSEDED

HTTP status 409 · code 1506

```text
The TaskRun is claimed by another dispatcher; this request comes from a superseded claimant and was not applied.
```

**Why it happens:** A dispatcher sent a start, an end or a log for a task it no longer holds, usually because Flow requeued the attempt after its lease lapsed. Flow changed nothing.

**What to do:** Nothing, for the task: its newer attempt stands. If it happens often, check that the dispatcher sends a heartbeat for every task it holds at least every 30 seconds.

**Related:** [Keep leases alive](https://www.useboomerang.io/docs/flow/main/extend/dispatcher-protocol#keep-leases-alive)

### TASKRUN_LOG_TOO_LARGE

HTTP status 413 · code 1507

```text
The TaskRun log is over the {…} byte limit (flow.engine.task.log.max-bytes) and was not stored.
```

**Why it happens:** A finished task's log is over `flow.engine.task.log.max-bytes`, 10 MiB by default. Flow refuses the whole log rather than cut it short.

**What to do:** Raise the property on service-core, or log less. The log stays readable from the pod while the pod exists.

**Related:** [Store finished logs](https://www.useboomerang.io/docs/flow/main/hosting/task-logs#store-finished-logs)

### TASKRUN_LOGS_DISABLED

HTTP status 503 · code 1508

```text
Task logs are not stored on this instance: the "Store Task Logs" artifact setting is off.
```

**Why it happens:** **Store Task Logs** is off in **Admin › Settings › Artifacts**, so Flow refuses a dispatcher's finished log.

**What to do:** Turn **Store Task Logs** on. Logs already stored are served until they expire.

**Related:** [Store finished logs](https://www.useboomerang.io/docs/flow/main/hosting/task-logs#store-finished-logs)

### DISPATCHER_NOT_REGISTERED

HTTP status 404 · code 2101

```text
Dispatcher "{…}" is not registered. Register again and use the id the engine answers with.
```

**Why it happens:** A dispatcher polled or sent a heartbeat under an ID Flow doesn't hold. Flow deletes a registration after 7 days without a connection, and a database reset loses every registration.

**What to do:** Nothing, with Flow's dispatcher SDK: it registers again and repeats the call. A dispatcher of your own must do the same.

**Related:** [Dispatcher protocol reference: Registration](https://www.useboomerang.io/docs/flow/main/extend/dispatcher-protocol#registration)

### DISPATCHER_INVALID_REQ

HTTP status 400 · code 2102

```text
Invalid dispatcher registration. A registration needs a host.
```

**Why it happens:** A dispatcher registered without a host.

**What to do:** Send the dispatcher's host in the registration.

**Related:** [Dispatcher protocol reference: Registration](https://www.useboomerang.io/docs/flow/main/extend/dispatcher-protocol#registration)

### TASK_INVALID_WORKFLOWREF

HTTP status 404 · code 1405, shared with `TASK_DELETE_IN_USE`

```text
Invalid Workflow reference provided. Task name: {…}.
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Tasks](https://www.useboomerang.io/docs/flow/main/fundamentals/tasks).

### TASKRUN_INVALID_PARAMS

HTTP status 400 · code 1503

```text
Parameters required have no been provided.
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Dispatcher protocol reference](https://www.useboomerang.io/docs/flow/main/extend/dispatcher-protocol#start-and-end-a-task).

## Workspaces

Errors from workspaces, their members and their quotas. Codes 1020, 1101–1105.

### QUOTA_EXCEEDED

HTTP status 429 · code 1020

```text
A quota has been exceeded. {…}: {…} / {…}
```

**Why it happens:** A workspace quota is reached. The message names it, with the usage and the limit, such as `Number of runs (executions): 20 / 20`. It can name `Number of Workflows`, `Number of runs (executions)`, `Concurrent runs (executions)`, `Requested Workspace size`, `Workspace Size Limit` or `Artifact storage (bytes)`.

**What to do:** Wait for a run to end or for the month to reset (UTC), delete workflows you no longer need, or ask an admin to raise the quota on **Manage workspace › Quotas**.

**Related:** [What happens at a limit?](https://www.useboomerang.io/docs/flow/main/webapp/quotas#what-happens-at-a-limit), [A run didn't start](https://www.useboomerang.io/docs/flow/main/introduction/troubleshooting#a-run-didnt-start)

### WORKSPACE_INVALID_REF

HTTP status 404 · code 1101

```text
Invalid Workspace reference has been provided.
```

**Why it happens:** No workspace with that name exists, or you aren't a member. On an install with `flow.workspace.single=true`, every workspace but `system` answers this.

**What to do:** Check the workspace's name, which is its slug, in the URL or the request. If you need access, ask an owner to add you.

**Related:** [Manage workspace: Members](https://www.useboomerang.io/docs/flow/main/webapp/manage#members)

### WORKSPACE_NON_UNIQUE_NAME

HTTP status 422 · code 1102

```text
Non-unique name provided is already in use. All names must be unique.
```

**Why it happens:** Another workspace already has that name, or the name is reserved: `home`, `admin`, `system`, `profile` and `connect` are. Flow compares names as slugs, so `My Team` and `my-team` collide.

**What to do:** Choose another name.

**Related:** [Manage workspace: Settings](https://www.useboomerang.io/docs/flow/main/webapp/manage#settings)

### WORKSPACE_INVALID_USER_ROLE

HTTP status 422 · code 1103

```text
An invalid Role has been provided for a User. Please valid the roles assigned to each member.
```

**Why it happens:** A member was given a role other than `owner`, `editor` or `reader`.

**What to do:** Use one of the three.

**Related:** [What can each role do?](https://www.useboomerang.io/docs/flow/main/webapp/manage#what-can-each-role-do)

### WORKSPACE_INVALID_REQ

HTTP status 400 · code 1104

```text
Invalid Workspace request has been provided.
```

**Why it happens:** Part of a workspace request is blank or not allowed: a blank name or display name, a blank approver group name, or creating or deleting a workspace on an install with `flow.workspace.single=true`.

**What to do:** Fill in the blank field. A single-workspace install has only the `system` workspace.

**Related:** [Manage workspace](https://www.useboomerang.io/docs/flow/main/webapp/manage)

### WORKSPACE_EXTERNAL_REF_TAKEN

HTTP status 409 · code 1105

```text
A workspace already carries this external reference: "{…}".
```

See: [Manage workspace](https://www.useboomerang.io/docs/flow/main/webapp/manage).

## Parameters

Errors from parameter names, types and values, at every layer. Codes 1209–1210, 1216–1217, 1801–1804.

### PARAM_NAME_COLLISION

HTTP status 400 · code 1209

```text
Parameter names {…} are case or separator variants of each other and would collide as the same PARAM_{…} environment variable. Rename them to differ by more than case, "-", or "_".
```

**Why it happens:** Two parameter names differ only by case, `-` or `_`, such as `my-key` and `MY_KEY`. A task receives each parameter as the environment variable `PARAM_<NAME>`, and the two would become the same variable.

**What to do:** Rename one, so the names differ by more than case and separators.

**Related:** [Parameters: Names](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters#names)

### PARAM_INVALID_NAME

HTTP status 400 · code 1210

```text
Parameter name "{…}" is invalid. Names may contain letters, digits, dashes and underscores, starting with a letter or underscore ("." is reserved as the reference path separator in parameter expressions, and "names" is reserved for the PARAM_NAMES manifest).
```

**Why it happens:** The name breaks the naming rule: it starts with a letter or underscore, then has only letters, digits, `-` and `_`. `names` is reserved in any case, and `.` separates the parts of a reference.

**What to do:** Use a name that fits the rule. A parameter's name can't change once created, so create a new one and update its references.

**Related:** [Parameters: Names](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters#names)

### PARAM_INVALID_TYPE

HTTP status 400 · code 1216

```text
Parameter type "{…}" is invalid. A parameter type is one of string, array, object or secret; leave it out for string.
```

**Why it happens:** A run request gives a parameter a `type` other than `string`, `array`, `object` or `secret`, such as `password`.

**What to do:** Use one of the four, or leave `type` out for `string`. A **Password** parameter's type is `secret`.

**Related:** [Parameters: Types](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters#types)

### PARAM_SECRET_NOT_STRING

HTTP status 400 · code 1217

```text
Parameter "{…}" is a secret, and a secret value must be a string.
```

**Why it happens:** A run request gives a secret parameter a value that isn't a string, such as a number or an object.

**What to do:** Send the secret's value as a JSON string.

**Related:** [Secured parameters](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters#secured-parameters)

### PARAMS_INVALID_REFERENCE

HTTP status 404 · code 1801

```text
Invalid param reference has been provided.
```

**Why it happens:** No global or workspace parameter with that name exists.

**What to do:** Check the name on the workspace's **Parameters** page, or in **Admin › Parameters**.

**Related:** [Where does a value come from?](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters#where-does-a-value-come-from)

### PARAMS_NON_UNIQUE_REFERENCE

HTTP status 400 · code 1802, shared with `PARAMS_NON_UNIQUE_KEY`

```text
Non-unique param reference provided. All params must have unique names.
```

**Why it happens:** A global parameter with that name already exists.

**What to do:** Choose another name, or edit the existing parameter.

**Related:** [Admin: Parameters](https://www.useboomerang.io/docs/flow/main/webapp/administer#parameters)

### PARAMS_INVALID_REQ

HTTP status 400 · code 1803

```text
Invalid param request has been provided.
```

See: [Parameters](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters).

### PARAMS_MANAGED_BY_INTEGRATION

HTTP status 409 · code 1804

```text
Parameter "{…}" is managed by the {…} integration and cannot be changed or deleted. Stop sharing the {…} credentials with tasks to remove it.
```

**Why it happens:** The workspace parameter belongs to an integration that shares its credentials, such as `github-token`. It shows **Managed by GitHub**, or the integration's name, and only the integration changes it.

**What to do:** Stop sharing the credentials, or disconnect the integration, to remove it. To use another value in one task, type it into the task's field instead of the reference.

**Related:** [Parameters an integration manages](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters#parameters-an-integration-manages)

### PARAMS_NON_UNIQUE_KEY

HTTP status 400 · code 1802, shared with `PARAMS_NON_UNIQUE_REFERENCE`

```text
Non unique param key provided is already in use. All params must have unique keys.
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Parameters](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters).

## Tokens and auth

Errors from sign-in, tokens, users and permission checks. Codes 101, 403, 1003–1008, 1010–1016.

### USER_NOT_FOUND

HTTP status 400 · code 101, shared with `USER_UNABLE_TO_DELETE`

```text
Unable to find user, or you do not have permission to view user.
```

**Why it happens:** Flow found no active user with that ID or email. A person an admin added by email stays inactive until their first sign-in, and Flow can't update them before then.

**What to do:** Check the ID or email. For someone an admin added recently, ask them to sign in once, then try again.

**Related:** [Name the first admin with the bootstrap token](https://www.useboomerang.io/docs/flow/main/hosting/sign-in#name-the-first-admin-with-the-bootstrap-token)

### USER_UNABLE_TO_DELETE

HTTP status 400 · code 101, shared with `USER_NOT_FOUND`

```text
Unable to close user account when user is a member of multiple teams.
```

**Why it happens:** The user is a member of a workspace. Despite the message, one workspace is enough to refuse the delete.

**What to do:** Remove the user from every workspace under **Manage workspace › Members**, then delete them.

**Related:** [Admin: Users](https://www.useboomerang.io/docs/flow/main/webapp/administer#users)

### PERMISSION_DENIED

HTTP status 401 · code 403

```text
Insufficient permission. This can happen because the Auth token does not have the right scopes, the user doesn't have permission, or the API has not been enabled.
```

**Why it happens:** Your credential reached the route but not what it acts on. Flow answers this for a few checks: reading the audit trail or platform-wide Insights, or changing another user, without a global grant; creating a workflow or task in a workspace you can't reach; creating a workspace while **Workspace creation by users** is off and you aren't an admin; sending a CloudEvent for a workflow you can't reach; and reading the log of a task in a run you can't reach. It carries code 403 but answers HTTP 401.

**What to do:** Use a token or account with the access the route needs. Most routes answer a missing permission with a bare `403` and no body instead.

**Related:** [What can each role do?](https://www.useboomerang.io/docs/flow/main/architecture/security#what-can-each-role-do), [Read an error](https://www.useboomerang.io/docs/flow/main/apis/overview#read-an-error)

### AUTH_REQUIRED

HTTP status 401 · code 1003

```text
Authentication is required to access this resource.
```

**Why it happens:** The request has no credential Flow accepts: no token, a token Flow doesn't hold, such as an expired or revoked one, or a kind of token the route doesn't take. The answer carries `WWW-Authenticate: Bearer`, and its message can say more than the one shown.

**What to do:** Send a current token of a kind the route takes, as `Authorization: Bearer <token>`. In the webapp, sign in again.

**Related:** [Security: Tokens](https://www.useboomerang.io/docs/flow/main/architecture/security#tokens), [Machine tokens](https://www.useboomerang.io/docs/flow/main/hosting/machine-tokens)

### AUTH_TOKEN_INVALID

HTTP status 401 · code 1004

```text
The provided id_token could not be verified.
```

**Why it happens:** Flow couldn't verify the id_token from your identity provider: its signature, issuer, audience, expiry or nonce doesn't check out, or it carries no email in `email`, `emailAddress` or an email-shaped `preferred_username`. Flow accepts only asymmetric signing algorithms.

**What to do:** Check the client registration with your provider: the token's audience is Flow's client ID, the signing algorithm is in the RS, PS or ES families, and the id_token carries an email.

**Related:** [Sign in with OpenID Connect](https://www.useboomerang.io/docs/flow/main/hosting/sign-in#sign-in-with-openid-connect)

### AUTH_NOT_CONFIGURED

HTTP status 400 · code 1005

```text
No trusted OIDC issuer is configured on this instance.
```

**Why it happens:** An OIDC sign-in reached Flow, but **OIDC Issuer** or **OIDC Client ID** is empty, or Flow couldn't read the issuer's discovery document or signing keys.

**What to do:** Set `FLOW_AUTH_OIDC_ISSUER` and `FLOW_AUTH_OIDC_CLIENT_ID`, or the settings in **Admin › Settings › Authentication**, and check that service-core can reach the issuer. Behind a forward proxy, set `proxy.host` and `proxy.port`.

**Related:** [Sign in with OpenID Connect](https://www.useboomerang.io/docs/flow/main/hosting/sign-in#sign-in-with-openid-connect)

### AUTH_ACTIVATION_REQUIRED

HTTP status 423 · code 1006

```text
This instance is not activated yet. Sign in again with its activation code.
```

**Why it happens:** Nobody has activated this install yet, and the sign-in carried no activation code. The webapp then shows the activation screen.

**What to do:** Enter the activation code, the value of `FLOW_ACTIVATION_CODE`, on the activation screen.

**Related:** [Make the first admin with the activation code](https://www.useboomerang.io/docs/flow/main/hosting/sign-in#make-the-first-admin-with-the-activation-code)

### AUTH_ACTIVATION_CODE_INVALID

HTTP status 400 · code 1007

```text
The activation code is not correct.
```

**Why it happens:** The activation code doesn't match `FLOW_ACTIVATION_CODE`. Nobody is created.

**What to do:** Enter the right code. With no code set, every code is refused: set `FLOW_ACTIVATION_CODE`, at least 32 characters, and restart service-core.

**Related:** [Make the first admin with the activation code](https://www.useboomerang.io/docs/flow/main/hosting/sign-in#make-the-first-admin-with-the-activation-code), [Sign-in fails](https://www.useboomerang.io/docs/flow/main/introduction/troubleshooting#sign-in-fails)

### AUTH_USER_NOT_ADMITTED

HTTP status 403 · code 1008

```text
You are not a user of this Flow install, and it does not create users at first sign-in. Ask an admin to add you to a workspace.
```

**Why it happens:** **Auto-Create Users** is off and you aren't a user yet: no admin has added you to a workspace, and no admin claim admits you. The webapp shows **Sign-in didn't complete**.

**What to do:** Ask an admin to add you by email in **Manage workspace › Members › Add members**, or to turn on **Auto-Create Users** in **Admin › Settings › Features**.

**Related:** [Decide who else may sign in](https://www.useboomerang.io/docs/flow/main/hosting/sign-in#decide-who-else-may-sign-in), [Sign-in fails](https://www.useboomerang.io/docs/flow/main/introduction/troubleshooting#sign-in-fails)

### TOKEN_INVALID_REQ

HTTP status 400 · code 1010

```text
Invalid Token request. Token type, name, and permissions are required. Principal is required for all but Global types.
```

**Why it happens:** The token request is missing its type or name, its principal for any kind but `global`, or its permissions for any kind but `user`.

**What to do:** Fill in the missing field.

**Related:** [Machine tokens](https://www.useboomerang.io/docs/flow/main/hosting/machine-tokens)

### TOKEN_INVALID_SESSION_REQ

HTTP status 400 · code 1011

```text
Invalid Token request. Session tokens cannot be created.
```

See: [Machine tokens](https://www.useboomerang.io/docs/flow/main/hosting/machine-tokens).

### TOKEN_INVALID_PERMISSION

HTTP status 400 · code 1012

```text
Invalid permissions provided as part of the Token request. Permissions must be in the format of scope (or **) / principal (or **) / action (READ|WRITE|ACTION|DELETE|**). If the principal is specified it must be a valid principal.
```

**Why it happens:** A permission isn't `<resource>/<action>` in lowercase with a known resource. The message describes an older three-part format with uppercase actions, which Flow doesn't accept.

**What to do:** Write each permission as `<resource>/<action>`, such as `workflow/read`, `workflowrun/action` or `workflow/**`.

**Related:** [Write permissions](https://www.useboomerang.io/docs/flow/main/hosting/machine-tokens#write-permissions), [The token permission error describes the wrong format](https://www.useboomerang.io/docs/flow/main/introduction/known-issues#the-token-permission-error-describes-the-wrong-format)

### TOKEN_INVALID_CEILING

HTTP status 400 · code 1013

```text
A key token can never be granted global-scoped permissions. Its ceiling is limited to the workspaces it is explicitly granted.
```

**Why it happens:** A `key` token asked for a global-scoped permission. A key token's permissions stay within the workspaces it's granted.

**What to do:** Grant the key token permissions on its workspace only, or have an admin create a `global` token.

**Related:** [Which token kinds are there?](https://www.useboomerang.io/docs/flow/main/hosting/machine-tokens#which-token-kinds-are-there)

### TOKEN_ADMIN_REQUIRED

HTTP status 403 · code 1014

```text
Creating a global token requires the requesting principal to already hold a global-scoped grant.
```

**Why it happens:** Creating a `global` token needs a credential that already holds a global grant, such as an admin's. Asking which permissions you can grant for a workspace where you can grant none gets this too.

**What to do:** Ask an admin to create the token, or create a token for your workspace under **Manage workspace › Tokens**.

**Related:** [Manage workspace: Tokens](https://www.useboomerang.io/docs/flow/main/webapp/manage#tokens), [Admin: Tokens](https://www.useboomerang.io/docs/flow/main/webapp/administer#tokens)

### TOKEN_DECLARED

HTTP status 409 · code 1015

```text
This token is declared in flow.security.tokens and cannot be changed through the API. Remove its entry from the configuration to revoke it.
```

**Why it happens:** The token is declared in configuration, under `flow.security.tokens`, so the token API can't change or delete it.

**What to do:** Remove its `FLOW_SECURITY_TOKENS_<NAME>_*` entries on every service-core instance and restart them. Flow revokes the token at the next start.

**Related:** [What service-core does with entries](https://www.useboomerang.io/docs/flow/main/hosting/machine-tokens#what-service-core-does-with-entries)

### TOKEN_INVALID_ACTOR

HTTP status 400 · code 1016

```text
Invalid Token request. A global token's actor can be SERVICE or AGENT, a key token's SERVICE, AGENT or WORKFLOW, and a user token has none.
```

**Why it happens:** The token's actor kind doesn't fit its kind: a `global` token takes `SERVICE`, `AGENT` or none; a `key` token takes `SERVICE`, `AGENT`, `WORKFLOW` or none; a `user` token takes none.

**What to do:** Choose an actor kind the token's kind allows. A dispatcher's token is `global` with `SERVICE`.

**Related:** [Which token kinds are there?](https://www.useboomerang.io/docs/flow/main/hosting/machine-tokens#which-token-kinds-are-there)

## Settings

Errors from changing the platform settings in **Admin › Settings**. Code 1030.

### SETTINGS_INVALID_KEY

HTTP status 400 · code 1030

```text
Invalid settings update. {…}
```

**Why it happens:** The body of a settings update isn't an object of groups, names a group or key the settings don't hold, or gives a value that isn't a single string, number or boolean. The message ends with the detail, such as `Unknown setting: features/autoCreate.`, and Flow writes nothing from the request.

**What to do:** Check the group and key against `GET /api/v2/settings`, and send each value as a string, number or boolean.

**Related:** [Update the settings](https://www.useboomerang.io/docs/flow/main/apis/SystemRoute#update-boomerang-flow-settings), [Admin: Settings](https://www.useboomerang.io/docs/flow/main/webapp/administer#settings)

## Integrations

Errors from connecting an integration and sharing its credentials with tasks. Codes 1901–1913.

### INTEGRATION_INVALID_REF

HTTP status 404 · code 1901

```text
Invalid integration reference has been provided.
```

See: [Integrations](https://www.useboomerang.io/docs/flow/main/webapp/integrations).

### INTEGRATION_INVALID_STATE

HTTP status 400 · code 1902

```text
The integration authorization request is invalid or has expired. Please retry connecting the integration.
```

**Why it happens:** The connection took more than 10 minutes from **Connect** to the end of the installation, or its state didn't check out, for example because **GitHub Private Key** changed during the install.

**What to do:** Select **Connect** again.

**Related:** [Fix a failed connection](https://www.useboomerang.io/docs/flow/main/guides/connect-github#fix-a-failed-connection)

### INTEGRATION_UNAUTHORIZED

HTTP status 403 · code 1903

```text
You do not have access to link or unlink this integration for the workspace.
```

**Why it happens:** You aren't a member of the workspace you're connecting, or you're disconnecting an installation that belongs to another workspace.

**What to do:** Ask an owner to add you to the workspace, or to connect it.

**Related:** [Who can connect and share?](https://www.useboomerang.io/docs/flow/main/webapp/integrations#who-can-connect-and-share)

### INTEGRATION_INSTALL_MISMATCH

HTTP status 403 · code 1904

```text
The GitHub installation could not be verified against your GitHub account.
```

**Why it happens:** Flow couldn't confirm that your GitHub account can see the installation. A wrong **GitHub Client ID** or **GitHub Client Secret** gives the same answer, because Flow then gets no access token for your account.

**What to do:** Install with a GitHub account that can manage the installation. If that doesn't help, ask an admin to check **GitHub Client ID** and **GitHub Client Secret**.

**Related:** [Fix a failed connection](https://www.useboomerang.io/docs/flow/main/guides/connect-github#fix-a-failed-connection), [Fix a GitHub setup](https://www.useboomerang.io/docs/flow/main/hosting/integrations#fix-a-github-setup)

### INTEGRATION_PARAM_EXISTS

HTTP status 409 · code 1905

```text
The workspace already has a parameter named "{…}". Rename or delete it before sharing the {…} credentials with tasks.
```

**Why it happens:** The workspace already has a parameter that someone created, with the name the integration shares, such as `github-token`.

**What to do:** Rename or delete that parameter on the workspace's **Parameters** page, then share again.

**Related:** [Share credentials with tasks](https://www.useboomerang.io/docs/flow/main/webapp/integrations#share-credentials-with-tasks)

### INTEGRATION_PARAMS_DISABLED

HTTP status 400 · code 1906

```text
Workspace parameters are turned off, so the {…} credentials cannot be shared with tasks. Turn on workspace parameters first.
```

**Why it happens:** **Admin › Settings › Features › Workspace Parameters** is off, so the credentials have nowhere to go.

**What to do:** Ask an admin to turn on **Workspace Parameters**, then share again.

**Related:** [Share credentials with tasks](https://www.useboomerang.io/docs/flow/main/webapp/integrations#share-credentials-with-tasks)

### INTEGRATION_TOKEN_FAILED

HTTP status 502 · code 1907

```text
Flow could not get an installation token from {…}. Check the integration settings and that the installation still exists.
```

**Why it happens:** Flow asked GitHub or Slack for a token and got none. For GitHub, **GitHub App ID** or **GitHub Private Key** is wrong, or the App was uninstalled. For Slack, the client ID or secret is wrong, or the installation holds no token.

**What to do:** Ask an admin to check the integration's settings, or install the app again.

**Related:** [Fix a GitHub setup](https://www.useboomerang.io/docs/flow/main/hosting/integrations#fix-a-github-setup), [Fix a Slack setup](https://www.useboomerang.io/docs/flow/main/hosting/integrations#fix-a-slack-setup)

### INTEGRATION_ALREADY_LINKED

HTTP status 409 · code 1908

```text
This workspace is already connected to another {…} installation. Disconnect it before connecting a different one.
```

**Why it happens:** The workspace is already connected to a different Slack installation. A workspace has one connection per integration. At this release only Slack raises this code.

**What to do:** Disconnect the current connection under **Manage**, then connect the other.

**Related:** [Disconnect](https://www.useboomerang.io/docs/flow/main/webapp/integrations#disconnect)

### INTEGRATION_TOKEN_ROTATES

HTTP status 400 · code 1909

```text
The {…} app has token rotation turned on, so its token expires and cannot be shared with tasks. Turn token rotation off in the {…} app settings and reinstall it.
```

**Why it happens:** The Slack app has token rotation on, so its token expires within 12 hours. Flow doesn't refresh Slack tokens, so it won't share one.

**What to do:** Turn token rotation off in the Slack app's settings, then install the app again.

**Related:** [Fix a Slack setup](https://www.useboomerang.io/docs/flow/main/hosting/integrations#fix-a-slack-setup)

### INTEGRATION_FIELD_REQUIRED

HTTP status 400 · code 1910

```text
{…} needs a value for "{…}".
```

See: [Integrations](https://www.useboomerang.io/docs/flow/main/webapp/integrations).

### INTEGRATION_FIELD_UNKNOWN

HTTP status 400 · code 1911

```text
{…} has no field named "{…}".
```

See: [Integrations](https://www.useboomerang.io/docs/flow/main/webapp/integrations).

### INTEGRATION_VALUES_NOT_ACCEPTED

HTTP status 400 · code 1912

```text
{…} fills its own credentials when it is installed, so it takes no field values.
```

See: [Integrations](https://www.useboomerang.io/docs/flow/main/webapp/integrations).

### INTEGRATION_NOT_CONFIGURED

HTTP status 409 · code 1913

```text
{…} is not set up: an administrator enters its client ID and client secret in the Integrations settings.
```

**Why it happens:** **Slack Client ID** or **Slack Client Secret** isn't set, so Flow can't start the Slack install. The Slack card's **Connect** is disabled, with "Not set up on this platform".

**What to do:** Ask an admin to set both in **Admin › Settings › Integrations**.

**Related:** [Fix a Slack setup](https://www.useboomerang.io/docs/flow/main/hosting/integrations#fix-a-slack-setup)

## Query

Errors from a request's filters or body, and generic request errors. Codes 429, 500, 1001–1002.

### DATA_CONVERSION_FAILED

HTTP status 500 · code 500

```text
Unable to convert data appropriately for the request.
```

**Why it happens:** Flow couldn't convert data for the response. It's a server error, not a fault in your request.

**What to do:** Try again. If it repeats, ask your operator to check the service-core log at that time.

**Related:** [Read an error](https://www.useboomerang.io/docs/flow/main/apis/overview#read-an-error)

### QUERY_INVALID_FILTERS

HTTP status 400 · code 1001

```text
Invalid query filters({…}) have been provided.
```

**Why it happens:** A filter or field in the request can't be read, and the message names it in the brackets, such as `labels`. Common causes: a `labels` entry that isn't `key=value`; a `statuses` or `phase` value Flow doesn't know; a callback `status` other than `succeeded` or `failed`; or a body field that fails validation.

**What to do:** Correct what the message names. `labels` takes URL-encoded `key=value` entries, separated by commas.

**Related:** [Page through a list](https://www.useboomerang.io/docs/flow/main/apis/overview#page-through-a-list), [Resume a waiting run with a callback](https://www.useboomerang.io/docs/flow/main/fundamentals/triggers#resume-a-waiting-run-with-a-callback)

### TOO_MANY_REQUESTS

HTTP status 429 · code 429, shared with `WORKFLOW_TRIGGER_DISABLED`

```text
Number of requests has exceeded the allowed number.
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Read an error](https://www.useboomerang.io/docs/flow/main/apis/overview#read-an-error).

### UNABLE_PATCH_REL

HTTP status 500 · code 1002

```text
Unable to patch relationship.
```

**Not returned in this release.** Flow defines this code, but no request returns it.

See: [Read an error](https://www.useboomerang.io/docs/flow/main/apis/overview#read-an-error).

## Task and run status reasons

A status reason says why a task or run ended the way it did. On the run page, a run's reason shows beside its status, and a task's shows as **Reason** under **View Details**, with its **Message** beside it. A task or run that ends for no cause of its own has none.

Each entry says who sets the reason. **Requeued** means the task never ran to an end, so Flow hands it to a dispatcher again before failing it. **Task retries don't apply** means the task's own **Retries** setting never repeats it, because a retry can't change the outcome. A reason Flow doesn't know is an ordinary failure.

### DispatchError

Set by a dispatcher

**What it means:** The dispatcher couldn't run the task, for example because it couldn't create the task's container. The task is **Failed**, and its **Message** says why.

**What to do:** Read the **Message**. A `forbidden` message means the dispatcher lacks a Kubernetes permission: ask your operator. Otherwise correct the task's image or settings.

**Related:** [When a task can't start](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#when-a-task-cant-start)

### DeadlineExceeded

Set by a dispatcher or Flow

**What it means:** The task or run used its timeout and ends **Timed Out**. A task that times out times out its run too. Time a task waits as **Ready** for a dispatcher counts.

**What to do:** Raise **Timeout** under **Configure › Run Options**, or the task's own timeout. If the task waited long as **Ready**, ask your operator to check the dispatcher.

**Related:** [Runs: Timeouts](https://www.useboomerang.io/docs/flow/main/fundamentals/runs#timeouts), [A task timed out](https://www.useboomerang.io/docs/flow/main/introduction/troubleshooting#a-task-timed-out)

### JobFailed

Set by a dispatcher

**What it means:** The task's container ran and failed, usually with a non-zero exit code. The task is **Failed**, and its **Message** carries the exit code and the end of its log.

**What to do:** Read the log with **View Log**, fix the script or its input, and retry. For a failure that passes, such as a service that was down, set **Retries** on the task.

**Related:** [Retry a run](https://www.useboomerang.io/docs/flow/main/guides/retry-a-run)

### JobDeleted

Set by a dispatcher

**What it means:** The task's Kubernetes Job or TaskRun was deleted before it finished.

**What to do:** Retry the run. If it keeps happening, ask your operator what deletes task pods in the namespace.

**Related:** [Clean up finished tasks](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#clean-up-finished-tasks)

### OOMKilled

Set by a dispatcher

**What it means:** The task's container ran out of memory and was killed.

**What to do:** Use less memory in the task, or ask your operator to raise `kube.resource.limit.memory` on the dispatcher. A memory-backed `/data` counts against the limit.

**Related:** [Size and place task pods](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#size-and-place-task-pods)

### ImagePull

Set by a dispatcher

**What it means:** The task's image couldn't be pulled: it doesn't exist, the tag is wrong, or the registry needs credentials the cluster doesn't have. The dispatcher fails the task after `kube.timeout.startFailureGraceSeconds`, 60 seconds by default.

**What to do:** Correct the image on the task or node. For a private registry, ask your operator about the pull secret, `kube.image.pullSecret`.

**Related:** [When a task can't start](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#when-a-task-cant-start)

### ImageNotAllowed

Set by a dispatcher · Task retries don't apply

**What it means:** The dispatcher refused the task's image before creating anything. Flow's Kubernetes dispatcher runs an `ai` task only when its image starts with an allowed prefix, `boomerangio/task-ai` by default.

**What to do:** Use an allowed image, or ask your operator to add your image's prefix to `flow.dispatcher.ai.image-prefixes`.

**Related:** [Run AI tasks](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#run-ai-tasks)

### AdmissionDenied

Set by a dispatcher · Task retries don't apply

**What it means:** An admission controller in the cluster refused the task's pod, such as a policy on images, resources or security settings.

**What to do:** Read the task's **Message** for the policy, then correct the task, or ask your operator about the policy.

**Related:** [When a task can't start](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#when-a-task-cant-start)

### ResultsTooLarge

Set by a dispatcher or Flow · Task retries don't apply

**What it means:** The task's results are over the limit: 4096 bytes together on Flow's Kubernetes dispatcher, or 1,048,576 bytes that Flow stores. A for-each task also fails this way when its items' combined results pass 16 MB.

**What to do:** Return less, and pass larger data by reference: a path on the run workspace, or an artifact. For an AI task, lower **Max tokens** or set **Output file**.

**Related:** [Stay within the size caps](https://www.useboomerang.io/docs/flow/main/guides/tasks#stay-within-the-size-caps)

### ExceededQuota

Set by a dispatcher · Requeued up to 3 times, then failed

**What it means:** The cluster had no room to create the task's pod, for example because a namespace quota refused it. The task never started.

**What to do:** Nothing at first: Flow requeues the task with backoff. If it fails after the requeues, ask your operator about the namespace's resource quota.

**Related:** [When a task can't start](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#when-a-task-cant-start)

### StartTimeout

Set by a dispatcher · Requeued up to 3 times, then failed

**What it means:** The task's pod was created but didn't start within the dispatcher's start deadline, `kube.timeout.startMinutes`, 15 minutes by default. It usually stayed `Pending` with no node to run on.

**What to do:** Nothing at first: Flow requeues the task. If it fails after the requeues, ask your operator about cluster capacity, node selectors and tolerations.

**Related:** [When a task can't start](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#when-a-task-cant-start)

### RateLimited

Set by a dispatcher · Requeued up to 3 times, then failed

**What it means:** The cluster, or a gateway in front of it, refused the task for rate. The task never started.

**What to do:** Nothing at first: Flow requeues the task with backoff. If it keeps failing, ask your operator about the cluster's API rate limits.

**Related:** [Which end reasons requeue a task?](https://www.useboomerang.io/docs/flow/main/extend/dispatcher-protocol#which-end-reasons-requeue-a-task)

### ClusterUnavailable

Set by a dispatcher · Requeued up to 3 times, then failed

**What it means:** The dispatcher couldn't reach the Kubernetes API server: a timeout, a refused connection or a 5xx answer. The task never started.

**What to do:** Nothing at first: Flow requeues the task. If it fails after the requeues, ask your operator to check the cluster's control plane and the dispatcher's route to it.

**Related:** [When a task can't start](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#when-a-task-cant-start)

### DispatcherStopping

Set by a dispatcher · Requeued up to 3 times, then failed

**What it means:** The dispatcher was stopping, for example in a rolling update, and handed the task back without starting it.

**What to do:** Nothing: Flow requeues the task for the next dispatcher that polls.

**Related:** [How leases and heartbeats work](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#how-leases-and-heartbeats-work)

### ConcurrencyLimit

Set by Flow

**What it means:** On a run: the workflow's **Concurrency limit** was reached and **Over the limit** is **Skip the run**, so Flow ended the run **Cancelled** at once.

**What to do:** Let the earlier runs finish, raise **Concurrency limit**, or choose **Queue until a run ends**.

**Related:** [Limit how many runs overlap](https://www.useboomerang.io/docs/flow/main/fundamentals/runs#limit-how-many-runs-overlap)

### WorkflowInvalid

Set by Flow

**What it means:** On a run: the workflow couldn't run, so the run ends **Invalid**. When the workflow has no task, or no path from the start to the end, no task starts and the message reads "Failed to run workflow: incomplete, or invalid, workflow". When Flow fails while queueing the run's tasks, the message reads "Failed to run workflow: unable to process Workflow and queue all tasks."

**What to do:** Fix the workflow in the editor, such as by linking a path from the start to the end, and save a new version.

**Related:** [Link tasks](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor#link-tasks), [A run didn't start](https://www.useboomerang.io/docs/flow/main/introduction/troubleshooting#a-run-didnt-start)

### FinallyFailed

Set by Flow

**What it means:** On a run: the graph succeeded, but a finally task ended **Failed**, **Timed Out** or **Invalid**, or the finally tasks exceeded their timeout. The run ends **Failed**, and its message names the finally task.

**What to do:** Read the finally task's **Message** and log, fix it, and run again.

**Related:** [Run a task after the run ends](https://www.useboomerang.io/docs/flow/main/guides/workflow-editor#run-a-task-after-the-run-ends)

### DispatchPrepareFailed

Set by Flow · Task retries don't apply

**What it means:** Flow couldn't prepare the task for its dispatcher after the claim, so the task failed before it started. The **Message** says why.

**What to do:** Read the **Message**. When the cause has passed, retry the run; otherwise ask your operator to check the service-core log.

**Related:** [Retry a run](https://www.useboomerang.io/docs/flow/main/guides/retry-a-run)

### SpecFillFailed

Set by Flow · Task retries don't apply

**What it means:** A workspace or global parameter that the task's script, command, arguments or environment references was deleted between the task's admission and its claim.

**What to do:** Recreate the parameter, or change the reference, then retry the run.

**Related:** [When do values resolve?](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters#when-do-values-resolve)

### DispatcherGone

Set by Flow

**What it means:** The dispatcher holding the task sent no poll or heartbeat for 60 seconds, so Flow treats it as gone. Flow requeues a container task up to 3 times for this, then ends it **Timed Out**.

**What to do:** Nothing at first. If tasks keep ending this way, ask your operator to check that the dispatcher is running and can reach service-core.

**Related:** [How leases and heartbeats work](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#how-leases-and-heartbeats-work)

### LeaseExpired

Set by Flow

**What it means:** The dispatcher holding the task didn't renew its lease in time: 90 seconds by default, renewed by a heartbeat every 30 seconds. Flow requeues a container task up to 3 times for this, then ends it **Timed Out**.

**What to do:** Nothing at first. If tasks keep ending this way, ask your operator to check the dispatcher's heartbeat, `flow.dispatcher.lease.beat-ms`, against `flow.dispatcher.lease-ms`.

**Related:** [How leases and heartbeats work](https://www.useboomerang.io/docs/flow/main/hosting/dispatcher#how-leases-and-heartbeats-work)

### ChildRunFailed

Set by Flow

**What it means:** A **Run Workflow** task waited for its child run, and the child ended other than **Succeeded**. The task is **Failed**.

**What to do:** Open the child run from the task's **View Activity**, and fix why it ended that way.

**Related:** [Child workflows](https://www.useboomerang.io/docs/flow/main/fundamentals/runs#child-workflows)

### NestingDepthExceeded

Set by Flow

**What it means:** A **Run Workflow** task is at the nesting limit, **Maximum Child Workflow Nesting Depth**, 5 levels by default, so it started nothing.

**What to do:** Shorten the chain of child workflows, or ask an admin to raise **Admin › Settings › Run limits › Maximum Child Workflow Nesting Depth**.

**Related:** [Child workflows](https://www.useboomerang.io/docs/flow/main/fundamentals/runs#child-workflows)

### ItemFailed

Set by Flow

**What it means:** At least one item of a for-each task didn't succeed, which fails the whole task. The message counts them, such as "2 of 10 items did not succeed." The other items still finish.

**What to do:** Select **Show items** on the run page to find the failed items. To carry on anyway, set the link after the task to always; to retry items, set **Retries** on the task.

**Related:** [When an item fails](https://www.useboomerang.io/docs/flow/main/guides/repeat-a-task-for-each-item#when-an-item-fails)

### ForeachItemsInvalid

Set by Flow

**What it means:** A for-each task's items didn't resolve to a JSON array when the task ran, so no item ran.

**What to do:** Check the reference in the task's items, such as `$(params.items)`, and that its value is an array.

**Related:** [Repeat a task for each item: Limits](https://www.useboomerang.io/docs/flow/main/guides/repeat-a-task-for-each-item#limits)

### ForeachTooManyItems

Set by Flow

**What it means:** A for-each task's items resolved to more entries than **Maximum For-Each Items** allows, 256 by default, so no item ran.

**What to do:** Split the list, or ask an admin to raise **Admin › Settings › Run limits › Maximum For-Each Items**.

**Related:** [Repeat a task for each item: Limits](https://www.useboomerang.io/docs/flow/main/guides/repeat-a-task-for-each-item#limits)

### ParamUnresolved

Set by Flow · Task retries don't apply

**What it means:** A reference in the task's fields, script, command, arguments or environment names a parameter no layer declares, a task not in the workflow, or a result that task doesn't declare. The task fails before its container starts, and its **Message** names the field, the reference and why.

**What to do:** Correct the reference, or declare the parameter. A credential such as `github-token` needs its integration connected and shared.

**Related:** [Why did a task fail with ParamUnresolved?](https://www.useboomerang.io/docs/flow/main/fundamentals/parameters#why-did-a-task-fail-with-paramunresolved), [A task failed with ParamUnresolved](https://www.useboomerang.io/docs/flow/main/introduction/troubleshooting#a-task-failed-with-paramunresolved)

### ArtifactNotFound

Set by Flow · Task retries don't apply

**What it means:** A **Download Artifact** task with **Optional** on found no artifact of that name. The task still ends **Succeeded**, with its `found` result set to `false`.

**What to do:** Nothing, when a missing file is expected, as on a first run. Otherwise check **Artifact name** and **Scope** against the upload.

**Related:** [Artifacts](https://www.useboomerang.io/docs/flow/main/fundamentals/artifacts#artifacts)

### ArtifactRefused

Set by Flow · Task retries don't apply

**What it means:** Flow refused an **Upload Artifact** or **Download Artifact** task: the name is invalid or taken, the file is too large, the workspace's **Artifact Storage** quota is full, the artifact has expired or doesn't exist, or nothing was uploaded. The task's **Message** is the matching error message.

**What to do:** Search this page for the **Message**: the artifact errors are under [Runs](#runs), and a full quota is `QUOTA_EXCEEDED`.

**Related:** [Artifacts: Limits](https://www.useboomerang.io/docs/flow/main/fundamentals/artifacts#limits)

## Next steps

- [Troubleshooting](https://www.useboomerang.io/docs/flow/main/introduction/troubleshooting): what to check, starting from what you see.
- [Known issues](https://www.useboomerang.io/docs/flow/main/introduction/known-issues): defects in this release and their workarounds.
- [Read an error](https://www.useboomerang.io/docs/flow/main/apis/overview#read-an-error): the API's error body.
- [Runs](https://www.useboomerang.io/docs/flow/main/fundamentals/runs): statuses, retries and timeouts.