A failed command prints an envelope whose error names a stable E_* code, the process exit code (exit) and whether running the operation again can succeed (retryable), with machine-readable details and a hint. This page is generated from the one table in the code that gives each code its exit code and retryable flag; swarmops schema ErrorCode prints the same codes and descriptions. Some codes are defined before any operation raises them: Known limitations names them.
| Code | Exit | Retryable | Description |
|---|---|---|---|
E_EXISTS |
1 | no | init found a store at the target path already. |
E_NOT_A_REPO |
6 | no | No store at the given path, or no store was named. |
E_IDENTITY_REQUIRED |
5 | no | A mutation was asked for without an identity. |
E_REV_NOT_FOUND |
6 | no | A revision names no changeset. |
E_AMBIGUOUS_ID |
1 | no | An id prefix matches more than one changeset; give more digits. |
E_PATH_NOT_FOUND |
6 | no | The path does not exist at that revision. |
E_IS_DIR |
1 | no | A file operation named a directory. |
E_TOO_LARGE |
1 | no | The content is larger than the operation allows. |
E_EMPTY_COMMIT |
1 | no | The commit changes nothing and allow_empty is off. |
E_TYPE_CONFLICT |
1 | no | A change puts an entry below a file, or a file onto a directory. |
E_UNKNOWN_PARENT |
6 | no | The parent changeset is not in the store. |
E_CAS_MISMATCH |
4 | yes | The ref no longer holds the expected target (or, with create, exists at another one); details.actual holds what it does, null when the ref does not exist. |
E_REF_NOT_FOUND |
6 | no | No ref by that name. |
E_REF_NAME_INVALID |
1 | no | The ref name is one no store format takes, or one the operation does not move: details.reason is reserved for a remote/ name, which only a fetch writes, and tag for a tag named as the target of a land or a commit's advance. |
E_STORE_CORRUPT |
1 | no | Stored data failed verification. |
E_INVALID_ARG |
2 | no | A malformed argument or request, including a command-line usage error. |
E_UNSUPPORTED_FS |
1 | no | The store path is not on a native Linux filesystem (for example WSL's /mnt/*). |
E_IO |
1 | no | The filesystem refused an operation: details.fs_op names it, and details.store_file the file of the store it was on, relative to the store's root. |
E_IO_TRANSIENT |
4 | yes | A journal append failed, and the store cut what it wrote back off the journal (details.committed is false): nothing was committed, so running the same operation again is safe. |
E_BUSY |
4 | yes | Another writer held the store's metadata lock for the whole wait, or commits landed during every one of a read's attempts to take a snapshot; nothing was committed (a commit's flushed objects may remain, for GC), and running the operation again can succeed. |
E_INTERNAL |
1 | no | A bug in SwarmOps, such as a caught panic. |
E_CONFLICT |
3 | no | The change conflicts with the target: details.report lists each conflicting file with its kind, its hunks and who changed it on the target. |
E_CAS_RETRY_EXHAUSTED |
4 | yes | The target moved before every one of the land's attempts could publish; nothing was recorded, and running the land again can succeed. |
E_NOTHING_TO_LAND |
1 | no | The land has nothing to add to the target: its head is on the target already, or its change is (details.reason says which). |
E_NOTHING_TO_UNDO |
1 | no | The operation moved no ref, so there is nothing to restore. |
E_OP_NOT_FOUND |
6 | no | The store has no operation by that number. |
E_AUTH |
5 | no | The serving entry could not name the caller, or no grant of the store's access file names it. |
E_POLICY_DENIED |
5 | no | The store's access file grants this identity no such action. |
E_MAINTENANCE_BUSY |
4 | yes | Another gc, repair or upgrade holds the store's maintenance lease; nothing was done, and running the operation again once it is done can succeed. |
E_FORMAT_REQUIRED |
1 | no | The ref name is one the store's format does not take but a later one does: details names name, needs (the format that takes it) and store (the store's); swarmops upgrade moves the store to it. |
E_TAG_IMMUTABLE |
1 | no | A tag was asked to move from one target to another: a tag is created and deleted, never moved (details.name). |
E_REF_PROTECTED |
1 | no | main was asked to be deleted: it is never deleted (details.name). |
E_GIT_NOT_A_REPO |
6 | no | git import found no git repository it can open at git_path (details.git_path). |
E_GIT_REF_NOT_FOUND |
6 | no | git import: the source repository has no git_ref, or it names no commit (details.git_ref; details.kind the object it names instead, such as a tree). |
E_GIT_IMPORT_DIVERGED |
3 | no | git import: the target ref's head is not the import of git_ref's commit or of an ancestor of it, because the source was rewritten, git_ref is behind the commit the head holds, or a native changeset was committed on the target, so nothing was written; there is no silent merge. |
E_GIT_IMPORT_LOSSY |
1 | no | git import: a commit holds content a changeset cannot keep as git has it; details names the commit, the path (also as path_base64 when it is not UTF-8) and the lossy class, which the request's lossy can allow. |
E_GIT_UNSUPPORTED |
1 | no | git import does not read the source: a SHA-256 repository, reftable refs, a shallow clone, a FIFO, a socket or a device where it reads a file of the git directory, a file it reads whole there that is longer than 16 MiB, a commit of more than 255 distinct parents (a parent listed twice counts once), or an entry whose mode is no kind of entry; details.reason says which (object_format, ref_storage, shallow, special_file, file_too_long, parents, mode), details.file names the file of special_file and file_too_long by its path in the git directory (details.size and details.max give the long one's length and the limit), and details.commit names the commit of parents and mode. |
E_GIT_READ |
1 | no | git import could not read the source: an object is missing (as in a partial clone), does not hash to its id or does not parse, or the filesystem refused a read (details.reason; details.object names the object when there is one). |
E_GIT_EXPORT_DIVERGED |
3 | no | git export: the branch holds commits that are not the export of the source ref's head or of an ancestor of it, so the branch did not move; there is no silent merge, and the request's force moves it anyway. |
E_GIT_WRITE |
1 | no | git export could not write the repository; details.reason says what failed: io (the filesystem refused a write; details.path names the file, relative to the git directory), ref_locked (the branch's lock file, refs/heads/<branch>.lock, exists: another git process holds it, or an earlier export died holding it, and git itself says to remove it once no git process runs; details.path names it) or ref_name_conflict (an existing ref stands where the branch's name needs a directory, or the other way round; details.branch). |
E_REMOTE_DIVERGED |
3 | no | A push or a sync found the remote branch elsewhere than it can move from: details.reason says why (remote_moved: it moved since the last fetch, and the push's compare-and-swap sent nothing; not_fast_forward; behind: the store ref is behind the remote; diverged; lossy_history; no_common_base: the sync found no changeset both hold), with remote, branch and, where known, expected and main_moved. |
E_REMOTE_REJECTED |
5 | no | The remote or git refused: details.reason is auth, not_found, declined (a hook or a rule of the remote's), bad_objects (a fetch received an object git's fsck refuses, or one its refs reach is missing; no tracking ref moved) or unclassified (a failure git's messages do not explain, never retried), with remote and what git said (refs, remote_messages, git_exit, stderr_tail, the token redacted). |
E_REMOTE_UNREACHABLE |
4 | yes | The network or the remote's host did not answer: details.phase (fetch, push, ls_remote) and details.cause (dns, connect, timeout, tls, disconnected, ssh). |
E_REMOTE_NOT_FOUND |
6 | no | The store records no remote of that name (details.remote). |
E_WS_EXISTS |
1 | no | ws create found a workspace of that name already, made by other arguments (details.name, details.path of the existing one). |
E_WS_NOT_FOUND |
6 | no | No workspace by that name, or at that path (details.name when named). |
E_WS_LOCKED |
4 | yes | Another mutation held the workspace's lock for the whole wait (details.holder, when it is known); running the operation again can succeed. |
E_WS_DIRTY |
1 | no | The workspace holds edits the operation would overwrite or lose (details.paths, the first 20); the hint names the command that commits or discards them. |
E_PATH_NOT_EMPTY |
1 | no | ws create was given a directory that holds something already (details.path). |
E_UNRESOLVED_CONFLICTS |
1 | no | A rebase still has conflicting paths no one resolved (details.paths). |
E_MARKERS_PRESENT |
1 | no | ws resolve found a conflict marker line still in a file (details.paths). |
E_WS_UNPORTABLE |
1 | no | The tree holds paths the workspace's volume cannot hold: details.reason says why (case_collision, windows_name, reserved_name) and details.paths names them. |
E_CHECK_FAILED |
1 | no | A workspace's check or bootstrap command failed or ran past its time (details.stage: check or bootstrap; exit_code, timed_out, the tails of its output, log, changeset). |
Exit 1. Retryable: no.
init found a store at the target path already.
Exit 6. Retryable: no.
No store at the given path, or no store was named.
Exit 5. Retryable: no.
A mutation was asked for without an identity.
Exit 6. Retryable: no.
A revision names no changeset.
Exit 1. Retryable: no.
An id prefix matches more than one changeset; give more digits.
Exit 6. Retryable: no.
The path does not exist at that revision.
Exit 1. Retryable: no.
A file operation named a directory.
Exit 1. Retryable: no.
The content is larger than the operation allows. details has one of four shapes: {size, limit, scope} for a limit of SwarmOps (scope put for one content, commit for a commit's contents together, request for a request's text, with the flag that named it as changes or resolve), where a commit adds the change's index and path, and file for a client file; {scope, size, limit, remote} for a push past a remote's limit (scope remote_file, which adds path, or remote_push); {store_limit, max, got} for an object longer than an object holds (store_limit object_bytes); and from git import, {commit, path, size, max} for a blob and {object, kind, size, max} for a commit, a tree or a tag.
Exit 1. Retryable: no.
The commit changes nothing and allow_empty is off.
Exit 1. Retryable: no.
A change puts an entry below a file, or a file onto a directory.
Exit 6. Retryable: no.
The parent changeset is not in the store.
Exit 4. Retryable: yes.
The ref no longer holds the expected target (or, with create, exists at another one); details.actual holds what it does, null when the ref does not exist.
Exit 6. Retryable: no.
No ref by that name.
Exit 1. Retryable: no.
The ref name is one no store format takes, or one the operation does not move: details.reason is reserved for a remote/ name, which only a fetch writes, and tag for a tag named as the target of a land or a commit's advance.
Exit 1. Retryable: no.
Stored data failed verification. A metadata file that does not parse also names details.fs_op and details.store_file.
Exit 2. Retryable: no.
A malformed argument or request, including a command-line usage error.
Exit 1. Retryable: no.
The store path is not on a native Linux filesystem (for example WSL's /mnt/*).
Exit 1. Retryable: no.
The filesystem refused an operation: details.fs_op names it, and details.store_file the file of the store it was on, relative to the store's root. A journal append it refused for want of permission or as a read-only filesystem also says details.committed: false: nothing was committed, and running the same operation again fails the same way until the hint's cause is fixed. git import also gives it for a frame that committed but failed after its commit point, with details.committed: true, details.warnings and no fs_op: the import stopped there, details.imported and details.last_commit say what it recorded, and the hint is to run it again, which continues after them.
Exit 4. Retryable: yes.
A journal append failed, and the store cut what it wrote back off the journal (details.committed is false): nothing was committed, so running the same operation again is safe. A failure after the commit point is no error: the operation succeeds, with a warning (but in git import, which stops there: E_IO). details.fs_op and details.store_file name the append that failed.
Exit 4. Retryable: yes.
Another writer held the store's metadata lock for the whole wait, or commits landed during every one of a read's attempts to take a snapshot; nothing was committed (a commit's flushed objects may remain, for GC), and running the operation again can succeed.
Exit 1. Retryable: no.
A bug in SwarmOps, such as a caught panic.
Exit 3. Retryable: no.
The change conflicts with the target: details.report lists each conflicting file with its kind, its hunks and who changed it on the target. Nothing was recorded; resolve the conflicts, then land again (the hint says how).
Exit 4. Retryable: yes.
The target moved before every one of the land's attempts could publish; nothing was recorded, and running the land again can succeed.
Exit 1. Retryable: no.
The land has nothing to add to the target: its head is on the target already, or its change is (details.reason says which).
Exit 1. Retryable: no.
The operation moved no ref, so there is nothing to restore.
Exit 6. Retryable: no.
The store has no operation by that number.
Exit 5. Retryable: no.
The serving entry could not name the caller, or no grant of the store's access file names it.
Exit 5. Retryable: no.
The store's access file grants this identity no such action.
Exit 4. Retryable: yes.
Another gc, repair or upgrade holds the store's maintenance lease; nothing was done, and running the operation again once it is done can succeed.
Exit 1. Retryable: no.
The ref name is one the store's format does not take but a later one does: details names name, needs (the format that takes it) and store (the store's); swarmops upgrade moves the store to it.
Exit 1. Retryable: no.
A tag was asked to move from one target to another: a tag is created and deleted, never moved (details.name). Nothing was written.
Exit 1. Retryable: no.
main was asked to be deleted: it is never deleted (details.name). Nothing was written.
Exit 6. Retryable: no.
git import found no git repository it can open at git_path (details.git_path).
Exit 6. Retryable: no.
git import: the source repository has no git_ref, or it names no commit (details.git_ref; details.kind the object it names instead, such as a tree).
Exit 3. Retryable: no.
git import: the target ref's head is not the import of git_ref's commit or of an ancestor of it, because the source was rewritten, git_ref is behind the commit the head holds, or a native changeset was committed on the target, so nothing was written; there is no silent merge. details names target_ref, target_head, git_head and base, the git commit the head stands for (the one it holds, or for a native head the one it exports to); and external_id (commit, changeset) where the import passed over an external id entry whose changeset stands for another commit, which verify --deep reports.
Exit 1. Retryable: no.
git import: a commit holds content a changeset cannot keep as git has it; details names the commit, the path (also as path_base64 when it is not UTF-8) and the lossy class, which the request's lossy can allow. The import stops before that commit, and the target ref does not move.
Exit 1. Retryable: no.
git import does not read the source: a SHA-256 repository, reftable refs, a shallow clone, a FIFO, a socket or a device where it reads a file of the git directory, a file it reads whole there that is longer than 16 MiB, a commit of more than 255 distinct parents (a parent listed twice counts once), or an entry whose mode is no kind of entry; details.reason says which (object_format, ref_storage, shallow, special_file, file_too_long, parents, mode), details.file names the file of special_file and file_too_long by its path in the git directory (details.size and details.max give the long one's length and the limit), and details.commit names the commit of parents and mode.
Exit 1. Retryable: no.
git import could not read the source: an object is missing (as in a partial clone), does not hash to its id or does not parse, or the filesystem refused a read (details.reason; details.object names the object when there is one).
Exit 3. Retryable: no.
git export: the branch holds commits that are not the export of the source ref's head or of an ancestor of it, so the branch did not move; there is no silent merge, and the request's force moves it anyway. details.reason says why: branch_ahead (commits made in git on top of the export of the head itself, which git import brings in), both_moved (commits made in git on top of an older export, while the source ref moved too), branch_moved (the branch names a commit that is no export of this history), source_moved_back (the source ref's head is behind the export the branch holds, after an undo or a ref set backwards), lossy_history (the branch holds the original commits of a history imported lossily, which the export would replace) or moved_during_export (another writer moved the branch while this export wrote; running the export again settles it, and what it wrote stays). The first five are found before anything is written. details also names branch, git_head (the commit the branch holds), head_changeset and, when the branch holds the export of a changeset, exported_changeset.
Exit 1. Retryable: no.
git export could not write the repository; details.reason says what failed: io (the filesystem refused a write; details.path names the file, relative to the git directory), ref_locked (the branch's lock file, refs/heads/<branch>.lock, exists: another git process holds it, or an earlier export died holding it, and git itself says to remove it once no git process runs; details.path names it) or ref_name_conflict (an existing ref stands where the branch's name needs a directory, or the other way round; details.branch). Running the export again after the cause is gone writes what is still missing.
Exit 3. Retryable: no.
A push or a sync found the remote branch elsewhere than it can move from: details.reason says why (remote_moved: it moved since the last fetch, and the push's compare-and-swap sent nothing; not_fast_forward; behind: the store ref is behind the remote; diverged; lossy_history; no_common_base: the sync found no changeset both hold), with remote, branch and, where known, expected and main_moved. Nothing was sent; the hint names the fetch or the sync to run.
Exit 5. Retryable: no.
The remote or git refused: details.reason is auth, not_found, declined (a hook or a rule of the remote's), bad_objects (a fetch received an object git's fsck refuses, or one its refs reach is missing; no tracking ref moved) or unclassified (a failure git's messages do not explain, never retried), with remote and what git said (refs, remote_messages, git_exit, stderr_tail, the token redacted).
Exit 4. Retryable: yes.
The network or the remote's host did not answer: details.phase (fetch, push, ls_remote) and details.cause (dns, connect, timeout, tls, disconnected, ssh). Nothing changed in the store; running the command again can succeed.
Exit 6. Retryable: no.
The store records no remote of that name (details.remote).
Exit 1. Retryable: no.
ws create found a workspace of that name already, made by other arguments (details.name, details.path of the existing one).
Exit 6. Retryable: no.
No workspace by that name, or at that path (details.name when named).
Exit 4. Retryable: yes.
Another mutation held the workspace's lock for the whole wait (details.holder, when it is known); running the operation again can succeed.
Exit 1. Retryable: no.
The workspace holds edits the operation would overwrite or lose (details.paths, the first 20); the hint names the command that commits or discards them.
Exit 1. Retryable: no.
ws create was given a directory that holds something already (details.path).
Exit 1. Retryable: no.
A rebase still has conflicting paths no one resolved (details.paths).
Exit 1. Retryable: no.
ws resolve found a conflict marker line still in a file (details.paths).
Exit 1. Retryable: no.
The tree holds paths the workspace's volume cannot hold: details.reason says why (case_collision, windows_name, reserved_name) and details.paths names them. Nothing was written.
Exit 1. Retryable: no.
A workspace's check or bootstrap command failed or ran past its time (details.stage: check or bootstrap; exit_code, timed_out, the tails of its output, log, changeset). Nothing was landed.