---
kind: reference
zz: "0.4.0"
updated: 2026-10-09
state: live
rules: https://zriz.io/llms.txt
---
# Errors of zriz

A run that does not pass has a `cause`. This page has one entry for each of the 60 reason words. 52 are for a run, 5 are for `zz` and 3 are op words.

The `cause` has four keys that a person reads. `reason` is a word from this page. `side` says who must act.

`retry` says if the same run can pass. `message` is one sentence that starts with a small letter.

The word `retry` has one of four values:

- `no`: The same run cannot pass. First change the target, the project or the runner config.
- `later`: The same run can pass after some time, with no change.
- `now`: The same run can pass at once. The fault was not in the run.
- `unknown`: The maker of the cause does not know.

The last four entries are errors of `zz` about the org. They are not reasons of a run.

In a pattern, `<name>` is a value of the run. `<id>` in a command is the id of the run. `<p>` is the name of your pipeline.

| Side | Meaning | Words |
|---|---|---|
| target | Your service did not do what the pipeline expects. | [assertion](#assertion), [http-error](#http-error), [sql-error](#sql-error), [browser-error](#browser-error), [cli-error](#cli-error), [timeout](#timeout), [connection-error](#connection-error), [poll-timeout](#poll-timeout), [poll-deadline-exceeded](#poll-deadline-exceeded), [pipeline-timeout](#pipeline-timeout), [capture-not-found](#capture-not-found), [explicit-fail](#explicit-fail) |
| pipeline | A file of the project is wrong, or the pipeline stopped the run. | [skipped](#skipped), [unknown-action](#unknown-action), [unsupported-resource-type](#unsupported-resource-type), [execution-error](#execution-error), [template-resolution-error](#template-resolution-error), [for-too-many-items](#for-too-many-items), [for-not-collection](#for-not-collection), [host-not-allowed](#host-not-allowed), [read-only](#read-only), [placeholder-in-disallowed-slot](#placeholder-in-disallowed-slot), [command-not-allowed](#command-not-allowed), [arg-not-allowed](#arg-not-allowed), [handle-busy](#handle-busy), [no-handle](#no-handle) |
| runner | The runner, its worker or the runner config was not ready. | [runner-unavailable](#runner-unavailable), [runner-down](#runner-down), [resource-unavailable](#resource-unavailable), [unknown-resource](#unknown-resource), [secret-not-listed](#secret-not-listed), [secret-not-set](#secret-not-set), [capture-lost](#capture-lost), [runner-restarted](#runner-restarted), [context-lost](#context-lost), [handle-lost](#handle-lost), [runner-at-capacity](#runner-at-capacity), [too-many-handles](#too-many-handles), [spawn-failed](#spawn-failed), [worker-unavailable](#worker-unavailable), [worker-mismatch](#worker-mismatch), [worker-error](#worker-error), [unknown-arg](#unknown-arg), [unknown-kind](#unknown-kind), [runner-no-answer](#runner-no-answer), [unexpected-frame](#unexpected-frame), [runner-error](#runner-error), [runner-busy](#runner-busy) |
| service | The zriz service had a fault. | [service-stall](#service-stall), [invalid-op](#invalid-op), [run-error](#run-error) |
| limit | A member of the org stopped the run. | [canceled](#canceled) |
| network | `zz` got no answer from the cloud. | [net-refused](#net-refused), [net-dns](#net-dns), [net-timeout](#net-timeout), [net-tls](#net-tls), [net-unknown](#net-unknown) |
| op words | The runner uses them. They are never the cause of a run. | [evidence-disabled](#evidence-disabled), [evidence-expired](#evidence-expired), [placeholder-not-found](#placeholder-not-found) |

## assertion {#assertion}

A check of the step failed. The value in the result of the target is not the value that the pipeline expects.

| Pattern | `check <check> of step <step-index> (<action>) failed: <path> is <actual> and the pipeline expects <expected>` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## http-error {#http-error}

The target answered with an HTTP status that the step does not accept.

| Pattern | `step <step-index> (<action>) got HTTP <http-status> from the target` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## sql-error {#sql-error}

The database of the target refused the query of the step.

| Pattern | `step <step-index> (<action>) failed: the database refused the query` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## browser-error {#browser-error}

A browser command of the step failed. `code` in the details names the error.

| Pattern | `step <step-index> (<action>) failed at browser command <command>: <code>` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## cli-error {#cli-error}

The command of the step ended with an error.

| Pattern | `step <step-index> (<action>) failed: the command ended with an error` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## timeout {#timeout}

The target did not answer before the time limit of the step.

| Pattern | `step <step-index> (<action>) got no answer from the target in <timeout-ms> ms` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## connection-error {#connection-error}

The runner could not open a connection to the target. The target did not accept the connection.

| Pattern | `step <step-index> (<action>) could not connect to the target` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## poll-timeout {#poll-timeout}

A poll step used all its attempts. The target never gave the expected state.

| Pattern | `step <step-index> (<action>) did not get the expected state in <attempts> attempts` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## poll-deadline-exceeded {#poll-deadline-exceeded}

The time limit of the pipeline ended while a poll step was in work. The target did not give the expected state in time.

| Pattern | `step <step-index> (<action>) did not get the expected state in <attempts> attempts and the pipeline limit of <timeout-ms> ms ended` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## pipeline-timeout {#pipeline-timeout}

The run used all the time that the pipeline allows. The run stopped at this step.

| Pattern | `the pipeline limit of <timeout-ms> ms ended at step <step-index> of <steps>` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## capture-not-found {#capture-not-found}

The step captures a value from the result of the target. The result does not hold that value.

| Pattern | `step <step-index> (<action>) did not find the value <name> in the result of the target` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## explicit-fail {#explicit-fail}

The pipeline has a fail step and the run reached it. The pipeline stopped the run on purpose.

| Pattern | `step <step-index> is a fail step of the pipeline` |
|---|---|
| Side | target |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`

## skipped {#skipped}

The pipeline has a skip step and the run reached it. The pipeline stopped the run on purpose.

| Pattern | `step <step-index> is a skip step of the pipeline` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## unknown-action {#unknown-action}

A step calls an action that the project does not define.

| Pattern | `step <step-index> calls the action <action> and the project has no such action` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## unsupported-resource-type {#unsupported-resource-type}

A resource has a type that this cloud does not know.

| Pattern | `resource <resource> has the type <type> and this cloud does not know it` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## execution-error {#execution-error}

The cloud could not make an op from the arguments of the step. An argument is not valid for the action.

| Pattern | `step <step-index> (<action>) has arguments that the cloud cannot make into an op` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## template-resolution-error {#template-resolution-error}

A step uses a reference to a value. No earlier step and no env file gives that value.

| Pattern | `step <step-index> uses <ref> and no earlier step or env file gives it` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## for-too-many-items {#for-too-many-items}

The list of a for step has more items than the limit allows.

| Pattern | `step <step-index> has a list of <items> items and the limit is <limit>` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## for-not-collection {#for-not-collection}

The value of a for step is not a list.

| Pattern | `step <step-index> is a for step and its value is not a list` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## host-not-allowed {#host-not-allowed}

The step calls an address that is not on the origin of the resource. The origin is the scheme, host and port of `base-url`. A redirect counts.

| Pattern | `step <step-index> (<action>) calls an address that is not on the origin of resource <resource>` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## read-only {#read-only}

The resource is read-only and the action writes. The runner did not send the statement to the database.

| Pattern | `step <step-index> (<action>) writes to resource <resource> and that resource is read-only` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## placeholder-in-disallowed-slot {#placeholder-in-disallowed-slot}

A secret placeholder is in a position that the runner does not permit.

| Pattern | `step <step-index> (<action>) has the placeholder <name> in a position that the runner does not permit` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## command-not-allowed {#command-not-allowed}

The step names a command that the runner config does not list for this resource.

| Pattern | `step <step-index> (<action>) names a command that resource <resource> does not have in the runner config` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## arg-not-allowed {#arg-not-allowed}

The step has an argument that the runner config does not permit for this resource.

| Pattern | `step <step-index> (<action>) has an argument that resource <resource> does not permit in the runner config` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## handle-busy {#handle-busy}

The step starts a handle that is in work.

| Pattern | `step <step-index> (<action>) starts the handle <handle> and that handle is in work` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## no-handle {#no-handle}

The step uses a handle that this run did not start.

| Pattern | `step <step-index> (<action>) uses the handle <handle> and this run started no such handle` |
|---|---|
| Side | pipeline |
| Retry | no |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the files of the project: `zz validate`

## runner-unavailable {#runner-unavailable}

No runner is connected for the env of the run. The run did not start.

| Pattern | `no runner is connected for the env <env>` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. Write the files of a runner for this machine and start it: `zz runners init --start`
2. See the runners of the org: `zz runners`

## runner-down {#runner-down}

The runner sent no request for more than 35 seconds during the run. The cloud counts such a runner as silent.

| Pattern | `the runner <runner> sent no request for <silent-ms> ms during step <step-index>` |
|---|---|
| Side | runner |
| Retry | later |

### Fix

1. See the runners of the org: `zz runners`
2. Run this pipeline again: `zz run <p>`

## resource-unavailable {#resource-unavailable}

The runner of the env does not have a resource that the pipeline uses. The run did not start.

| Pattern | `the runner <runner> of the env <env> does not have <count> resources of the pipeline: <resources>` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. See the runners of the org: `zz runners`
2. Show the failed step and its values: `zz runs <id>`

## unknown-resource {#unknown-resource}

The runner config has no resource with this id and type, or its connection is not open.

| Pattern | `step <step-index> (<action>) uses resource <resource> and the runner <runner> cannot open it` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. See the runners of the org: `zz runners`
2. Show the failed step and its values: `zz runs <id>`

## secret-not-listed {#secret-not-listed}

The step uses a secret that the resource does not list in the runner config.

| Pattern | `step <step-index> (<action>) uses the secret <name> and resource <resource> does not list it in the runner config` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. See the runners of the org: `zz runners`
2. Show the failed step and its values: `zz runs <id>`

## secret-not-set {#secret-not-set}

The runner has no value for the secret that the step uses.

| Pattern | `step <step-index> (<action>) uses the secret <name> and the runner <runner> has no value for it` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. See the runners of the org: `zz runners`
2. Show the failed step and its values: `zz runs <id>`

## capture-lost {#capture-lost}

The runner does not hold a value that an earlier step captured. The runner probably restarted.

| Pattern | `the runner <runner> does not have the captured value <name> of this run at step <step-index>` |
|---|---|
| Side | runner |
| Retry | now |

### Fix

1. See the runners of the org: `zz runners`
2. Run this pipeline again: `zz run <p>`

## runner-restarted {#runner-restarted}

The runner restarted during the run. It lost the state of the run.

| Pattern | `the runner <runner> restarted during the run and lost <lost>` |
|---|---|
| Side | runner |
| Retry | now |

### Fix

1. See the runners of the org: `zz runners`
2. Run this pipeline again: `zz run <p>`

## context-lost {#context-lost}

The browser context of the run closed before the step. The message gives the reason.

| Pattern | `step <step-index> (<action>) lost its browser context: <why>` |
|---|---|
| Side | runner |
| Retry | now |

### Fix

1. See the runners of the org: `zz runners`
2. Show the time of each step: `zz runs <id> --timeline`

## handle-lost {#handle-lost}

The runner lost a handle that an earlier step started. The message gives the reason.

| Pattern | `step <step-index> (<action>) lost its handle <handle>: <why>` |
|---|---|
| Side | runner |
| Retry | now |

### Fix

1. See the runners of the org: `zz runners`
2. Show the time of each step: `zz runs <id> --timeline`

## runner-at-capacity {#runner-at-capacity}

All slots of a limit of the runner were busy. The step waited and no slot came free in time.

| Pattern | `step <step-index> (<action>) could not start: all <limit> <unit> of <scope> were busy for <waited-ms> ms` |
|---|---|
| Side | runner |
| Retry | later |

### Fix

1. See the runners of the org: `zz runners`
2. Show the time of each step: `zz runs <id> --timeline`

## too-many-handles {#too-many-handles}

The worker is at its limit of handles. The step could not start a new handle.

| Pattern | `step <step-index> (<action>) could not start a handle: the limit of <limit> handles is in use` |
|---|---|
| Side | runner |
| Retry | later |

### Fix

1. See the runners of the org: `zz runners`
2. Show the time of each step: `zz runs <id> --timeline`

## spawn-failed {#spawn-failed}

The worker could not start the command of the step.

| Pattern | `step <step-index> (<action>) could not start its command on the runner <runner>` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. See the runners of the org: `zz runners`
2. Show the failed step and its values: `zz runs <id>`

## worker-unavailable {#worker-unavailable}

The step needs the worker of the runner. The runner cannot connect to the worker.

| Pattern | `step <step-index> (<action>) needs the worker and the runner <runner> cannot connect to it` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. See the runners of the org: `zz runners`
2. Show the failed step and its values: `zz runs <id>`

## worker-mismatch {#worker-mismatch}

The worker refused the request of the runner. The message gives the reason of the worker.

| Pattern | `the worker of the runner <runner> refused the request of step <step-index>: <worker-reason>` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. See the runners of the org: `zz runners`
2. Show the failed step and its values: `zz runs <id>`

## worker-error {#worker-error}

The worker had an internal error. The cloud does not know the cause.

| Pattern | `the worker of the runner <runner> had an internal error at step <step-index>` |
|---|---|
| Side | runner |
| Retry | unknown |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. See the runners of the org: `zz runners`

## unknown-arg {#unknown-arg}

The runner does not know an argument that the cloud sent. The build of the runner is too old.

| Pattern | `the runner <runner> does not know an argument of step <step-index>: its build is too old` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. Install the newest version of zz: `zz upgrade`
2. See the runners of the org: `zz runners`

## unknown-kind {#unknown-kind}

The runner does not know the kind of op that the cloud sent. The build of the runner is too old.

| Pattern | `the runner <runner> does not know the op kind <kind> of step <step-index>: its build is too old` |
|---|---|
| Side | runner |
| Retry | no |

### Fix

1. Install the newest version of zz: `zz upgrade`
2. See the runners of the org: `zz runners`

## runner-no-answer {#runner-no-answer}

The runner got the op and gave no answer in time.

| Pattern | `the runner <runner> got the op of step <step-index> and gave no answer in <timeout-ms> ms` |
|---|---|
| Side | runner |
| Retry | now |

### Fix

1. See the runners of the org: `zz runners`
2. Run this pipeline again: `zz run <p>`

## unexpected-frame {#unexpected-frame}

The runner sent a message that is not an answer to the op.

| Pattern | `the runner <runner> sent a frame that is not an answer at step <step-index>` |
|---|---|
| Side | runner |
| Retry | unknown |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. See the runners of the org: `zz runners`

## runner-error {#runner-error}

The runner could not do the step and does not know why. The message gives the place where it failed.

| Pattern | `the runner <runner> could not do step <step-index> and does not know the cause: <where>` |
|---|---|
| Side | runner |
| Retry | unknown |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. See the runners of the org: `zz runners`

## runner-busy {#runner-busy}

The op waited more than 2 seconds for the runner. The runner had all its slots in work.

| Pattern | `step <step-index> (<action>) waited <wait-ms> ms for the runner <runner>: the runner had <busy> of <limit> <unit> in work` |
|---|---|
| Side | runner |
| Retry | later |

### Fix

1. See the runners of the org: `zz runners`
2. Run this pipeline again: `zz run <p>`

## service-stall {#service-stall}

The op waited for the runner. The runner was connected and not busy. The zriz service did not send the op.

| Pattern | `step <step-index> (<action>) waited <wait-ms> ms for the runner <runner>: the runner was connected and not busy, and the zriz service did not send the op` |
|---|---|
| Side | service |
| Retry | later |

### Fix

1. Show the time of each step: `zz runs <id> --timeline`
2. Run this pipeline again: `zz run <p>`

## invalid-op {#invalid-op}

The cloud made an op that the wire protocol refuses. This is a fault of zriz.

| Pattern | `the cloud made an op for step <step-index> that the wire protocol refuses` |
|---|---|
| Side | service |
| Retry | unknown |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the connection to the cloud: `zz doctor`

## run-error {#run-error}

The cloud could not do the run and does not know why. The message gives the place where it failed.

| Pattern | `the cloud could not do the run and does not know the cause: <where>` |
|---|---|
| Side | service |
| Retry | unknown |

### Fix

1. Show the failed step and its values: `zz runs <id>`
2. Check the connection to the cloud: `zz doctor`

## canceled {#canceled}

A member canceled the run.

| Pattern | `a member canceled the run at step <step-index>` |
|---|---|
| Side | limit |
| Retry | now |

### Fix

1. Run this pipeline again: `zz run <p>`

## net-refused {#net-refused}

`zz` could not connect. The service refused the connection.

| Pattern | `the service at <host> refused the connection` |
|---|---|
| Side | network |
| Retry | later |

### Fix

1. Check the connection to the cloud: `zz doctor`

## net-dns {#net-dns}

The name of the service did not resolve.

| Pattern | `the name <host> did not resolve` |
|---|---|
| Side | network |
| Retry | later |

### Fix

1. Check the connection to the cloud: `zz doctor`
2. Show the commands of zz: `zz`

## net-timeout {#net-timeout}

The service did not answer in time.

| Pattern | `the service at <host> gave no answer in <timeout-ms> ms` |
|---|---|
| Side | network |
| Retry | later |

### Fix

1. Check the connection to the cloud: `zz doctor`

## net-tls {#net-tls}

The TLS handshake with the service failed.

| Pattern | `the TLS handshake with <host> failed` |
|---|---|
| Side | network |
| Retry | no |

### Fix

1. Check the connection to the cloud: `zz doctor`
2. Show the commands of zz: `zz`

## net-unknown {#net-unknown}

The request failed and `zz` does not know why.

| Pattern | `the request to <host> failed and zz does not know the cause` |
|---|---|
| Side | network |
| Retry | unknown |

### Fix

1. Check the connection to the cloud: `zz doctor`

## evidence-disabled {#evidence-disabled}

The runner refused an evidence op because evidence is off in its config. This word does not fail a run. It is only in the log of the runner, in a line with `op refused`.

| Kind | Op word. It is never the cause of a run. |
|---|---|


### Fix

1. Set `evidence` in the runner config to a value that is not `none`, or remove the key. Then start the runner again.

## evidence-expired {#evidence-expired}

The runner refused an evidence op because it holds no excerpt for that call. This word does not fail a run. It is only in the log of the runner, in a line with `op refused`.

| Kind | Op word. It is never the cause of a run. |
|---|---|


### Fix

1. Read the failed step: `zz runs <id>`. Its error gives the cause without the excerpt.

## placeholder-not-found {#placeholder-not-found}

A placeholder in a step is not a listed secret and not a captured value. The cloud changes this word to `runner-restarted`, `capture-lost` or `secret-not-listed`.

| Pattern | `step <step-index> (<action>) uses the placeholder <name>: it is not a listed secret of resource <resource> and not a captured value of this run` |
|---|---|
| Kind | Op word. It is never the cause of a run. |

### Fix

1. Read the reason word of the run: `zz runs <id>`.

## org-mismatch {#org-mismatch}

The org in use is not the org of the project. The exit code is 3.

### Fix

1. Remove `--org`. Unset `ZZ_ORG`. In CI, use a key of the project org.
2. Use a login of the project org: `zz --org work run <pipeline>`
3. Add that login: `zz login --add`
4. To move the project, change `org` in `.zriz/project.json`.
5. Do the run again: `zz run <pipeline>`

## no-current-org {#no-current-org}

`zz` has many logins and no current login. The exit code is 3.

### Fix

1. Make one login the current login: `zz switch work`
2. Do the command again: `zz runners`

## unknown-login {#unknown-login}

The value of `--org`, `ZZ_ORG`, `zz switch`, or `zz logout` is not a login name. An org id is valid when one login has it. The exit code is 2.

### Fix

1. List the login names: `zz switch`
2. Use one name: `zz --org work runners`

## org-not-set {#org-not-set}

`.zriz/project.json` has no `org`, and the command sends project data or changes an org item. The exit code is 2.

### Fix

1. Write the org to the project: `zz init <work folder>`. With many logins: `zz --org work init <work folder>`
2. Do the command again: `zz run <pipeline>`