Skip to content

Errors and exit codes

A failure carries a stable code. Text output ends its error line with it, as wdx: ... [not_found]; with --json, stdout holds Problem Details with the same code (see JSON output). The exit code says what kind of failure it was: 1 rejected, 2 usage, 3 a system failure.

The AI coding agent is not installed or is disabled, or none is installed and enabled.

Exit 1 · HTTP 409 · returned by wdx agent create, wdx agent models, wdx agent restart, wdx agent start

The agent’s AI coding agent cannot do this yet.

Exit 1 · HTTP 409 · returned by wdx agent restart, wdx agent transcript, wdx prompt

The agent is in the middle of something, which this would lose.

Exit 1 · HTTP 409 · returned by wdx agent restart, wdx agent start

The agent’s AI coding agent is not running.

Exit 1 · HTTP 409 · returned by wdx agent attach, wdx agent send, wdx message resend, wdx prompt

The agent was removed and stays only for its children.

Exit 1 · HTTP 409 · returned by wdx agent create, wdx agent remove, wdx agent rename, wdx agent restart, wdx agent send, wdx agent start, wdx prompt

The agent is already starting or running.

Exit 1 · HTTP 409 · returned by wdx agent remove, wdx agent start

An agent is working in the worktree.

Exit 1 · HTTP 409 · returned by wdx plan task done, wdx plan task land, wdx worktree land, wdx worktree rebase

This node is logged in to a hub already.

Exit 1 · HTTP 409 · returned by wdx hub login

A daemon already serves this home.

Exit 1 · HTTP 409 · returned by wdx daemon start

The agent’s holder could not answer the prompt, or did not see the answer taken.

Exit 3 · HTTP 500 · returned by wdx prompt

The terminal was started by a wdx too old to attach to.

Exit 1 · HTTP 409 · returned by wdx agent attach, wdx terminal attach

A row of the node’s audit chain does not match its hash: the chain was changed.

Exit 1 · HTTP 409 · returned by wdx hub audit verify

The base moved during the check.

Exit 1 · HTTP 409 · returned by wdx worktree land

The PR below is merged on GitHub, but not in the local default branch.

Exit 1 · HTTP 409 · returned by wdx worktree rebase

A new worktree’s branch already exists.

Exit 1 · HTTP 409 · returned by wdx agent create, wdx plan run

The question was answered no.

Exit 1 · HTTP 409 · returned by wdx deps install, wdx doc remove, wdx hub code setup, wdx hub node remove, wdx plan cancel, wdx plan remove, wdx project open, wdx prompt

The project’s check failed.

Exit 1 · HTTP 409 · returned by wdx worktree land

None of the project’s checkouts is left on disk.

Exit 1 · HTTP 409 · returned by wdx doc sync-to-git, wdx project create, wdx project open

The downloaded release does not match its checksum.

Exit 3 · HTTP 502 · returned by wdx update

Git clone failed.

Exit 1 · HTTP 502 · returned by wdx project create, wdx project open

An authenticator code is set up on this node already.

Exit 1 · HTTP 409 · returned by wdx hub code setup

No authenticator code is set up on the node.

Exit 1 · HTTP 409 · returned by wdx hub code recover, wdx hub session open · and by every command with --node

The code is wrong, used already, or came too soon after a wrong one.

Exit 1 · HTTP 403 · returned by wdx hub code recover, wdx hub code setup, wdx hub session open · and by every command with --node

The connection to the terminal or node ended before it answered.

Exit 3 · HTTP 503 · returned by wdx agent attach, wdx terminal attach · and by every command with --node

The daemon is not running or not answering.

Exit 3 · HTTP 503 · returned by wdx agent acas, wdx agent attach, wdx agent create, wdx agent get, wdx agent list, wdx agent models, wdx agent remove, wdx agent rename, wdx agent restart, wdx agent send, wdx agent start, wdx agent transcript, wdx daemon restart, wdx daemon start, wdx doc create, wdx doc get, wdx doc history, wdx doc list, wdx doc remove, wdx doc rename, wdx doc set, wdx doc sync-to-git, wdx doc update, wdx hub audit verify, wdx hub code recover, wdx hub code setup, wdx hub login, wdx hub logout, wdx hub node get, wdx hub node list, wdx hub node remove, wdx hub session close, wdx hub session list, wdx hub session open, wdx hub status, wdx message discard, wdx message list, wdx message resend, wdx plan archive, wdx plan cancel, wdx plan copy, wdx plan create, wdx plan get, wdx plan history, wdx plan list, wdx plan pause, wdx plan remove, wdx plan rename, wdx plan resume, wdx plan run, wdx plan set, wdx plan status, wdx plan task done, wdx plan task get, wdx plan task land, wdx plan task retry, wdx plan task skip, wdx plan unarchive, wdx plan update, wdx project close, wdx project create, wdx project get, wdx project landing, wdx project list, wdx project open, wdx project remove, wdx project sync, wdx prompt, wdx terminal attach, wdx terminal create, wdx terminal get, wdx terminal history, wdx terminal list, wdx terminal remove, wdx terminal send, wdx terminal start, wdx usage, wdx worktree comments, wdx worktree diff, wdx worktree land, wdx worktree list, wdx worktree rebase, wdx worktree remove · and by every command with --node

A program the request needs is not installed: wdx deps list tells which.

Exit 3 · HTTP 503 · returned by wdx project create, wdx project get, wdx project open, wdx worktree land, wdx worktree rebase

The worktree is on no branch, so a PR has none to push.

Exit 1 · HTTP 409 · returned by wdx worktree land, wdx worktree rebase

The doc has a newer revision than the base given.

Exit 1 · HTTP 409 · returned by wdx doc update

The release could not be found or downloaded.

Exit 3 · HTTP 502 · returned by wdx update

An editor has the file, or a file in the directory, open.

Exit 1 · HTTP 409

Git would not move the base forward.

Exit 1 · HTTP 409 · returned by wdx worktree land

The terminal’s holder and a client on another node speak no version in common: the terminal was started by a wdx too old for relayed clients, or the client’s is too old for the holder.

Exit 1 · HTTP 409 · returned by wdx agent attach, wdx terminal attach

The hub cannot be reached, or did not answer as a hub does.

Exit 3 · HTTP 502 · returned by wdx hub login, wdx hub node get, wdx hub node list, wdx hub node remove, wdx hub session open · and by every command with --node

The hub serves no version of the API this wdx speaks.

Exit 1 · HTTP 409 · returned by wdx hub login, wdx hub node get, wdx hub node list, wdx hub node remove, wdx hub session open · and by every command with --node

The package manager failed.

Exit 3 · HTTP 502 · returned by wdx deps install

An unexpected failure: database, filesystem or git.

Exit 3 · HTTP 500 · returned by wdx agent acas, wdx agent attach, wdx agent create, wdx agent get, wdx agent list, wdx agent models, wdx agent remove, wdx agent rename, wdx agent restart, wdx agent send, wdx agent start, wdx agent transcript, wdx completion bash, wdx completion fish, wdx completion zsh, wdx daemon restart, wdx daemon start, wdx daemon status, wdx daemon stop, wdx deps install, wdx deps list, wdx doc create, wdx doc get, wdx doc history, wdx doc list, wdx doc remove, wdx doc rename, wdx doc set, wdx doc sync-to-git, wdx doc update, wdx hub audit verify, wdx hub code recover, wdx hub code setup, wdx hub login, wdx hub logout, wdx hub node get, wdx hub node list, wdx hub node remove, wdx hub session close, wdx hub session list, wdx hub session open, wdx hub status, wdx message discard, wdx message list, wdx message resend, wdx observe start, wdx observe status, wdx observe stop, wdx plan archive, wdx plan cancel, wdx plan copy, wdx plan create, wdx plan get, wdx plan history, wdx plan list, wdx plan pause, wdx plan remove, wdx plan rename, wdx plan resume, wdx plan run, wdx plan set, wdx plan status, wdx plan task done, wdx plan task get, wdx plan task land, wdx plan task retry, wdx plan task skip, wdx plan unarchive, wdx plan update, wdx project close, wdx project create, wdx project get, wdx project landing, wdx project list, wdx project open, wdx project remove, wdx project sync, wdx prompt, wdx setting get, wdx setting list, wdx setting set, wdx setting write, wdx terminal attach, wdx terminal create, wdx terminal get, wdx terminal history, wdx terminal list, wdx terminal remove, wdx terminal send, wdx terminal start, wdx tide, wdx update, wdx usage, wdx version, wdx worktree comments, wdx worktree diff, wdx worktree land, wdx worktree list, wdx worktree rebase, wdx worktree remove

An argument is empty or malformed.

Exit 1 · HTTP 422 · returned by wdx agent create, wdx doc create, wdx doc list, wdx doc set, wdx doc update, wdx hub login, wdx plan copy, wdx plan create, wdx plan run, wdx plan set, wdx plan update, wdx project open

The name is not allowed.

Exit 1 · HTTP 422 · returned by wdx agent create, wdx agent rename, wdx doc create, wdx doc rename, wdx plan copy, wdx plan create, wdx plan rename, wdx project create, wdx project open, wdx terminal create

The path cannot be used.

Exit 1 · HTTP 422 · returned by wdx doc sync-to-git, wdx message list, wdx project create, wdx project open, wdx worktree comments, wdx worktree diff, wdx worktree land, wdx worktree list, wdx worktree rebase, wdx worktree remove

The plan’s YAML has problems: details.problems lists them.

Exit 1 · HTTP 422 · returned by wdx plan copy, wdx plan create, wdx plan update

The setting cannot take that value, or cannot be set.

Exit 1 · HTTP 422

The project has not said how it lands.

Exit 1 · HTTP 409 · returned by wdx worktree land

The worktree is already landing.

Exit 1 · HTTP 409 · returned by wdx worktree land

The login was cancelled, or another replaced it.

Exit 1 · HTTP 409 · returned by wdx hub login

The login was denied on the hub, or the account is disabled.

Exit 1 · HTTP 403 · returned by wdx hub login

The login was not approved in time.

Exit 1 · HTTP 410 · returned by wdx hub login

Something else has this name.

Exit 1 · HTTP 409 · returned by wdx agent create, wdx agent rename, wdx doc create, wdx doc rename, wdx hub login, wdx plan copy, wdx plan create, wdx plan rename, wdx project create, wdx project open, wdx terminal create

The worktree has no local branch to land on.

Exit 1 · HTTP 409 · returned by wdx worktree land, wdx worktree rebase

No previous version is kept to roll back to.

Exit 1 · HTTP 409 · returned by wdx update

The project has no git remote, whose key the hub files its docs under.

Exit 1 · HTTP 422 · returned by wdx project sync

The node is this one: leaving is wdx hub logout.

Exit 1 · HTTP 409 · returned by wdx hub node remove

The node showed a key other than the one pinned for it in an earlier session.

Exit 1 · HTTP 409 · returned by wdx hub session open · and by every command with --node

The account has no node of this name or id.

Exit 1 · HTTP 404 · returned by wdx hub node get, wdx hub node remove, wdx hub session open · and by every command with --node

The node is not connected to the hub, or did not answer in time.

Exit 1 · HTTP 409 · returned by wdx hub session open · and by every command with --node

The two nodes speak no version in common between them: update the older.

Exit 1 · HTTP 409 · returned by wdx hub session open · and by every command with --node

The worktree has files not committed.

Exit 1 · HTTP 409 · returned by wdx plan task done, wdx plan task land, wdx worktree land, wdx worktree rebase

Nothing has this name or id.

Exit 1 · HTTP 404 · returned by wdx agent attach, wdx agent create, wdx agent get, wdx agent list, wdx agent models, wdx agent remove, wdx agent rename, wdx agent restart, wdx agent send, wdx agent start, wdx agent transcript, wdx doc create, wdx doc get, wdx doc history, wdx doc list, wdx doc remove, wdx doc rename, wdx doc set, wdx doc sync-to-git, wdx doc update, wdx message discard, wdx message list, wdx message resend, wdx plan archive, wdx plan cancel, wdx plan copy, wdx plan create, wdx plan get, wdx plan history, wdx plan list, wdx plan pause, wdx plan remove, wdx plan rename, wdx plan resume, wdx plan run, wdx plan set, wdx plan status, wdx plan task done, wdx plan task get, wdx plan task land, wdx plan task retry, wdx plan task skip, wdx plan unarchive, wdx plan update, wdx project close, wdx project get, wdx project landing, wdx project open, wdx project remove, wdx project sync, wdx prompt, wdx terminal attach, wdx terminal create, wdx terminal get, wdx terminal history, wdx terminal list, wdx terminal remove, wdx terminal send, wdx terminal start, wdx worktree comments, wdx worktree diff, wdx worktree land, wdx worktree list, wdx worktree rebase, wdx worktree remove

The path is not in a git repository.

Exit 1 · HTTP 422 · returned by wdx project open

This node is not logged in to a hub, or the hub cut it off.

Exit 1 · HTTP 409 · returned by wdx hub code recover, wdx hub code setup, wdx hub logout, wdx hub node get, wdx hub node list, wdx hub node remove, wdx hub session open · and by every command with --node

The worktree has nothing ahead of its base.

Exit 1 · HTTP 409 · returned by wdx worktree land

The release is older than the installed version.

Exit 1 · HTTP 409 · returned by wdx update

Something is already at the path, as the directory to clone into.

Exit 1 · HTTP 409 · returned by wdx agent create, wdx doc get, wdx plan get, wdx project open

The plan has a newer revision than the base given.

Exit 1 · HTTP 409 · returned by wdx plan update

A plan of plans lists the plan.

Exit 1 · HTTP 409 · returned by wdx plan remove, wdx plan rename, wdx plan run

The plan is not done or cancelled, or a plan it waits for is not done.

Exit 1 · HTTP 409 · returned by wdx plan archive, wdx plan run, wdx plan unarchive

The work of a plan it waits for is not in the default branch.

Exit 1 · HTTP 409 · returned by wdx plan run

The plan is not running or paused.

Exit 1 · HTTP 409 · returned by wdx plan cancel, wdx plan pause, wdx plan resume, wdx plan set, wdx plan task done, wdx plan task land, wdx plan task retry, wdx plan task skip

The plan has run: only a draft can be changed or run.

Exit 1 · HTTP 409 · returned by wdx plan remove, wdx plan rename, wdx plan run, wdx plan update

A port the observability stack needs is taken.

Exit 1 · HTTP 409 · returned by wdx observe start

Gh did not open the pull request.

Exit 1 · HTTP 409 · returned by wdx worktree land

Installing needs root, and sudo cannot ask for the password.

Exit 1 · HTTP 403 · returned by wdx deps install

The project is closed.

Exit 1 · HTTP 409 · returned by wdx agent create, wdx agent restart, wdx agent start, wdx plan resume, wdx plan run, wdx terminal create, wdx terminal start, wdx worktree land, wdx worktree rebase

Terminals or agents are running in the project.

Exit 1 · HTTP 409 · returned by wdx project close, wdx project create, wdx project open, wdx project remove

The repository is a worktree of one project but has the origin of another.

Exit 1 · HTTP 409 · returned by wdx project open

The agent’s prompt is not the one answered, or changed while it was answered.

Exit 1 · HTTP 409 · returned by wdx prompt

Git refused to push the branch.

Exit 1 · HTTP 409 · returned by wdx worktree land, wdx worktree rebase

The rebase stopped and was undone.

Exit 1 · HTTP 409 · returned by wdx worktree land, wdx worktree rebase

The recovery key is wrong, or came too soon after a wrong one.

Exit 1 · HTTP 403 · returned by wdx hub code recover

The daemon cannot use the config file and keeps the settings it has.

Exit 1 · HTTP 422

The node allows no sessions: hub.remote_access is off there.

Exit 1 · HTTP 403 · returned by wdx hub session open · and by every command with --node

An agent cannot run commands on another node.

Exit 1 · HTTP 403 · and by every command with --node

The directory is already in a git repository.

Exit 1 · HTTP 409 · returned by wdx project create, wdx project open

Rolling back needs the database backup, losing the changes since the update.

Exit 1 · HTTP 409 · returned by wdx update

The node does not serve this through a session, or does not have it.

Exit 1 · HTTP 403 · and by every command with --node

Docker or Podman failed.

Exit 3 · HTTP 502 · returned by wdx observe start, wdx observe status, wdx observe stop

Neither Docker nor Podman is installed.

Exit 3 · HTTP 503 · returned by wdx observe start, wdx observe stop

The message did not reach the terminal’s holder.

Exit 3 · HTTP 500 · returned by wdx agent send, wdx message resend, wdx terminal send

The host closed the session: it went idle, its daemon restarted, remote access went off, the hub cut a node off, or it was closed.

Exit 1 · HTTP 409 · returned by wdx hub session open · and by every command with --node

No session of this id is open.

Exit 1 · HTTP 404 · returned by wdx hub session close

No session into the node is open: open one with its code.

Exit 1 · HTTP 409 · and by every command with --node

The release does not accept a value the config file sets.

Exit 1 · HTTP 422 · returned by wdx update

The holder, the shell or the AI coding agent did not start.

Exit 3 · HTTP 500 · returned by wdx agent create, wdx agent restart, wdx agent start, wdx terminal create, wdx terminal start

The plan’s task is not in a state the request needs.

Exit 1 · HTTP 409 · returned by wdx plan task done, wdx plan task land, wdx plan task retry, wdx plan task skip

The terminal’s shell is not running.

Exit 1 · HTTP 409 · returned by wdx message resend, wdx terminal attach, wdx terminal send

The terminal is already starting or running.

Exit 1 · HTTP 409 · returned by wdx terminal remove, wdx terminal start

A TIDE is already running for this home.

Exit 1 · HTTP 409 · returned by wdx tide

The account has as many streams open through the hub as it may.

Exit 1 · HTTP 429 · returned by wdx hub session open · and by every command with --node

Wdx cannot install it on this system: the instructions say how to by hand.

Exit 1 · HTTP 422 · returned by wdx deps install

The update or rollback failed and was undone.

Exit 3 · HTTP 500 · returned by wdx update

Another update or rollback is running.

Exit 1 · HTTP 409 · returned by wdx update

The request, command line or a setting is invalid.

Exit 2 · HTTP 400 · returned by wdx agent acas, wdx agent attach, wdx agent create, wdx agent get, wdx agent list, wdx agent models, wdx agent remove, wdx agent rename, wdx agent restart, wdx agent send, wdx agent start, wdx agent transcript, wdx completion bash, wdx completion fish, wdx completion zsh, wdx daemon restart, wdx daemon start, wdx daemon status, wdx daemon stop, wdx deps install, wdx deps list, wdx doc create, wdx doc get, wdx doc history, wdx doc list, wdx doc remove, wdx doc rename, wdx doc set, wdx doc sync-to-git, wdx doc update, wdx hub audit verify, wdx hub code recover, wdx hub code setup, wdx hub login, wdx hub logout, wdx hub node get, wdx hub node list, wdx hub node remove, wdx hub session close, wdx hub session list, wdx hub session open, wdx hub status, wdx message discard, wdx message list, wdx message resend, wdx observe start, wdx observe status, wdx observe stop, wdx plan archive, wdx plan cancel, wdx plan copy, wdx plan create, wdx plan get, wdx plan history, wdx plan list, wdx plan pause, wdx plan remove, wdx plan rename, wdx plan resume, wdx plan run, wdx plan set, wdx plan status, wdx plan task done, wdx plan task get, wdx plan task land, wdx plan task retry, wdx plan task skip, wdx plan unarchive, wdx plan update, wdx project close, wdx project create, wdx project get, wdx project landing, wdx project list, wdx project open, wdx project remove, wdx project sync, wdx prompt, wdx setting get, wdx setting list, wdx setting set, wdx setting write, wdx terminal attach, wdx terminal create, wdx terminal get, wdx terminal history, wdx terminal list, wdx terminal remove, wdx terminal send, wdx terminal start, wdx tide, wdx update, wdx usage, wdx version, wdx worktree comments, wdx worktree diff, wdx worktree land, wdx worktree list, wdx worktree rebase, wdx worktree remove

A rebase, a merge or the like is in progress in the worktree.

Exit 1 · HTTP 409 · returned by wdx worktree land, wdx worktree rebase

Git could not add the worktree.

Exit 1 · HTTP 422 · returned by wdx agent create

The worktree is a slot of a plan going on.

Exit 1 · HTTP 409 · returned by wdx worktree land, wdx worktree rebase, wdx worktree remove

The project’s clone cannot be removed.

Exit 1 · HTTP 409 · returned by wdx worktree land, wdx worktree rebase, wdx worktree remove

The worktree has commits or changes that have not landed.

Exit 1 · HTTP 409 · returned by wdx worktree remove

Git would not remove the worktree.

Exit 1 · HTTP 409 · returned by wdx worktree remove

The worktree is not on the branch the request needs.

Exit 1 · HTTP 409 · returned by wdx plan task done, wdx plan task land