devmachine

Troubleshooting

Troubleshooting

Where the logs are

When something went wrong and you want help, these files say what happened. Find the folder with devmachine config path.

  • <config>/logs/devmachine.log — the CLI’s own log. A command that changes a machine (setup, machines add, sync, update, doctor, packages add, run, login, credentials push and the like) writes a start line with the version, system and command line, every line it printed, Ansible’s output included, and an end line with how it ended and how long it took. Any other command writes one line when it fails. devmachine logs path prints where it is, and a failed command prints it as its last line: log: <path>.
  • devmachine.log.1, .2, .3, in the same folder — older runs. At 5 MB the log moves to .1 and a new one starts; only three old ones are kept.
  • <config>/history.log — one line per command that reached a machine: when, which machine or workspace, ok or failed, and the command. No output.
  • ~/Library/Logs/Devmachine/app.log — written by the macOS app, not the CLI: what the app did and the errors it met.

What is taken out: before a line reaches devmachine.log, passwords, tokens, API keys, Authorization and Bearer headers, GitHub and Tailscale keys, private keys, .env values, values given to secrets set and any NAME=value whose name says token, secret, password, key or auth become ***. A password you type or pipe in is never written: the log copies what the CLI prints, not what it reads. Addresses, host names and machine, workspace and user names stay, because without them the log says nothing. The full list is in the CLI’s log.

How to send them: read the file first, then attach devmachine.log (and .1 if the run you mean is older) to the issue or message. To send only the run that failed, copy from its start line to its end line; the number in brackets is the same on each line of one run.

ssh <workspace>-devmachine: “Could not resolve hostname”

What it means: That name only exists as a Host entry in ~/.ssh/config, and it is missing — either you said no when setup asked about it, or it was set up before that question existed.

What to do:

devmachine aliases --write

Say yes when it asks. devmachine ssh <workspace> and mosh <workspace> still work either way — only the plain ssh/mosh form, and tools that dial ssh themselves (VS Code Remote-SSH, Zed, the macOS app), need the alias. See SSH aliases.

A new workspace’s alias works for a moment, then “Could not resolve hostname”

What it means: The aliases ended up in two files. Something else owns ~/.ssh/config — a template, a dotfiles manager — and keeps the aliases in a file it Includes, while the CLI was writing its block into ~/.ssh/config itself. The next time that tool rewrote ~/.ssh/config, the CLI’s block went with it, and the included file never learned about the new workspace.

What to do: Tell the CLI where the aliases live, once: devmachine aliases --write --path ~/.ssh/<that-file> --yes. It records the file as ssh_aliases_path, empties the block it had left in ~/.ssh/config, and every later change — a new workspace, a new machine — is written there.

“workspace X lives on Y, not Z”

What it means: sync --workspace X --machine Z names two things that do not match: the configuration puts workspace X on machine Y. The sync stops before it connects, so nothing changed on either machine.

What to do: Drop --machine. sync --workspace finds the machine the workspace lives on by itself.

“several machines are configured: say which one with —machine”

What it means: You have more than one server configured, and this command needs to know which one to act on.

What to do: Add --machine <name>, or use a workspace name — that already says which server it lives on.

doctor never says this: with several machines and no --machine, it checks every one of them.

Commands hang for a minute or more right after the computer wakes

What it means: An older CLI kept its shared SSH connection open across the sleep. The connection was dead, and each command waited on it until the system gave up. The SSH agent’s prompt, such as 1Password’s, only appeared after that.

What to do: Update the CLI. It now drops a dead connection within a few seconds and logs in again. See Session indicators.

login-waiting from sessions

What it means: The machine is fine and accepted your key. Your SSH agent has not signed with it yet: 1Password waits for Touch ID or to be unlocked, as it does after a wake. The login stays open, so nothing is asked of the machine again while it waits.

What to do: Approve the prompt in 1Password (or unlock your agent). The next sessions lists the sessions. If no prompt shows, open 1Password: a locked app may be waiting behind other windows. See Session indicators.

“no address answered”

What it means: Nothing answered at the address devmachine tried. The error lists every address it tried and what happened for each.

What to do:

  • Check the port. A server on a non-standard port needs port: set in its configuration.
  • Check for a second address — see Addresses and fallback.

“connection refused” on a machine that answered before

The error ends with:

machine "main": no address answered: 203.0.113.10 (dial tcp 203.0.113.10:22: connect: connection refused); this machine answered SSH before, so the server may be blocking this address after failed logins (fail2ban, for example): …

What it means: devmachine has talked to this server before — its host key is trusted — and now the server turns the connection away before any login: refused, or closed during the handshake. SSH is most likely still running. The usual cause is fail2ban, or another firewall rule, that banned your address after several failed logins in a short time. A key the server refuses, tried again and again by doctor, sessions or the macOS app, is enough. The port can still look open from another network, because the ban is for your address only.

devmachine adds this sentence only for a server it has reached before. For an address it has never seen, “connection refused” means the usual: wrong address or port, or SSH not running.

What to do:

  • Stop whatever keeps logging in with the wrong key — a machine left in config.yml with a key that does not work, or the macOS app polling it.
  • Wait about 10 minutes: fail2ban lifts a ban on its own (bantime, 10 minutes by default).
  • Or open the provider’s web console, which does not go through SSH, and run sudo fail2ban-client status sshd to see the banned addresses, then sudo fail2ban-client set sshd unbanip <your address>.
  • Then fix the key — see “answered on … but refused the login”.

setup and machines add never write a machine whose key has not logged in, so they do not start this loop — see nothing is written before the key logs in.

“answered on … but refused the login”

What it means: The server is there, so the network is fine. The account or the key is the problem.

What to do:

  • Check that account exists on the server. A workspace in your configuration is not created on the server until you run sync.
  • Check the key is allowed to log in to that account.

A new workspace shows as unreachable until sync

What it means: A workspace you just added is in your configuration, but its account on the machine does not exist until sync finishes. Until then, the machine refuses every login to it. devmachine sessions reports this as login-refused, not unreachable: the machine is fine, and the other workspaces on it still answer.

Each refused login is a failed login in the machine’s SSH log. With fail2ban on, enough of them in a short time block your address for the whole machine, so do not keep asking about a workspace that is not synced yet.

What to do: Run devmachine sync. When it finishes, the workspace answers.

“no key in the configuration and no SSH agent”

What it means: devmachine has nothing to log in with.

What to do: Either set key: on the server to a private key, or start an SSH agent and load one.

machines add: “the key does not log in yet and no password was given”

What it means: machines add --address … asks nothing, so it had no way to get the server’s password, and the key it chose is not in the admin’s authorized_keys yet. A server just bought usually takes only a password. Nothing was changed, and nothing was written to config.yml, so nothing keeps retrying the key until the server bans your address.

What to do: Give the password on stdin, so it never appears in the command line or the shell history:

printf '%s' "$PASSWORD" | devmachine machines add … --password-stdin

Or put the key’s public half (<key>.pub) in the admin’s authorized_keys through the provider’s console, and run the same command again.

create-local refuses --cpus, --memory or --disk

What it means: The size you asked for does not fit this computer, so no VM was made. The CPUs can be at most the computer’s cores. The memory must be less than the computer’s, because macOS or Linux needs some for itself while the VM runs. The disk must be at least 10 GiB, or the first sync fills it.

What to do: Run it again with a number inside the range the message gives.

create-local --add: “the local machine … is running, and was not added”

What it means: The VM was created and is running, but adding it failed — the error after the colon says which step. Nothing was written to config.yml, so nothing points at a half-added machine.

What to do: Fix the cause, then run the command the error ends with. It is the whole machines add for the running VM — name, address, port, the host key’s fingerprint, the public password on stdin, and the flags you gave — ready to copy:

printf '%s' devmachine | devmachine machines add --name sandbox --address 127.0.0.1 \
  --port 60022 --fingerprint SHA256:… --password-stdin

Or throw the VM away with devmachine machines delete-local <name> and run create-local --add again.

It used to connect, and now it does not

What it means: If you recently added keys to your SSH agent, that is very likely the cause, and only on a machine with neither key: nor agent_key: in its configuration. A server gives up after a few tries, and an agent holding many keys can use them all up before it reaches the one that works.

A machine with key: or agent_key: set is immune to this: devmachine offers that one key and nothing else. Plain ssh, and anything else on your computer, is not — it still asks the agent for everything it holds.

What to do: On a machine with neither field yet, devmachine setup and devmachine machines add only choose a key the first time — run them again on an existing machine and they resume, without asking. Set the field by hand in config.yml instead: key: <path> for a file, or agent_key: <public key line> (ssh-add -L lists what your agent holds, in that format) for one from the agent. Full explanation: SSH: logging in and knowing it is your server.

“the SSH agent does not hold the key … that this machine logs in with”

What it means: The machine’s agent_key: names a key your SSH agent is not currently offering — the password manager it lives in is locked, or SSH_AUTH_SOCK points at a different agent than the one that key is in.

What to do: Unlock the password manager (1Password, say) and try again. If that does not fix it, check SSH_AUTH_SOCK:

echo $SSH_AUTH_SOCK
ssh-add -l

Compare the fingerprint ssh-add -l lists against the one the error names. If they never match, agent_key: in config.yml names the wrong key: replace it by hand with the line ssh-add -L prints for the key you meant.

“ansible-playbook is not on the machine”

What it means: sync runs Ansible, the tool devmachine uses to apply packages, on the server — so the server needs it installed.

What to do: Run devmachine setup --machine <name>, which installs it, or install it once by hand: apt install ansible on Debian and Ubuntu, pacman -S ansible on Arch. Everything after that is sync’s job. doctor still tells you the truth about everything else without it.

“this CLI does not set up ”…” yet”

this CLI does not set up "fedora" yet: it supports debian, ubuntu and arch, and systems based on them

What it means: The machine runs Linux, and neither ID nor ID_LIKE in its /etc/os-release names Debian, Ubuntu or Arch Linux. setup and machines add stop before changing anything: no key was installed, password login is as it was, nothing was written to config.yml. doctor reports the same thing as a failed operating system check.

What to do: Use a machine with Debian, Ubuntu or Arch Linux — most providers offer all three. Installing Ansible by hand does not get past the check: the packages that sync applies are written for those three.

”… which is based on …: … devmachine is not tested on it”

203.0.113.10 runs manjaro, which is based on arch: it is set up the arch way, but devmachine is not tested on it.

What it means: Not an error. ID in /etc/os-release is not one the CLI knows, but ID_LIKE says the system is based on one it does. setup goes on, and installs Ansible and runs the packages as it would on that base. doctor shows the same sentence as a warning.

What to do: Nothing, while it works. If a package fails on the derivative and not on the base, the derivative has renamed or left out something the base has: see based on Debian, Ubuntu or Arch.

”… is not a system this CLI sets up”

"FreeBSD" is not a system this CLI sets up: it supports Linux (debian, ubuntu, arch) and macOS

What it means: uname -s on the machine said neither Linux nor Darwin (macOS). The CLI stopped there, before changing anything.

What to do: Point the command at a Linux server (Debian, Ubuntu or Arch Linux) or a Mac. Your own Mac is set up differently: devmachine machines add --self <name>, see your computer as a machine.

“pacman could not install ansible”

pacman could not install ansible from the package lists this machine has.
They are probably older than the mirrors: bring the machine up to date with pacman -Syu, then run this again.

What it means: On Arch, setup installs Ansible with pacman -S and the package lists the machine already has. The mirrors keep only the newest version of each package, so on a server whose lists are weeks old the version pacman asks for is gone, and the download fails. setup does not refresh the lists on its own: pacman -Sy without -u is a partial upgrade, which can leave Ansible built for a Python the machine does not have. The key is installed and proved; if hardening ran, password login is already off.

What to do: On the machine, as root, bring it up to date with pacman -Syu, then run the same setup or machines add command again. The key now logs in, so no password is asked for.

“the admin login cannot become root”

What it means: The machine’s user in config.yml is not root, and sudo -n true fails as that account — its sudo wants a password, or it has none. The CLI needs root to turn password login off, install Ansible and run sync, and nobody is there to type a password, so it stops before changing anything.

What to do: Either log in as root (user: root, with the key in root’s authorized_keys), or give the account passwordless sudo, once, on the machine:

echo 'alice ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/devmachine-alice
sudo chmod 440 /etc/sudoers.d/devmachine-alice

Then run the command again. See an admin login that is not root.

setup fails with “Could not open lock file … Permission denied”, or sync with “sending a directory to /opt/devmachine … mkdir: Permission denied”

What it means: The admin login is not root, and the CLI is older than the one that runs system steps through sudo -n. Those versions ran apt-get, the SSH hardening and the bundle upload as the admin itself.

What to do: Update the CLI (devmachine update) and run the same command again. Nothing was half-applied: both errors happen before the first change. If it then says “the admin login cannot become root”, see the entry above.

setup says the machine “answered through Tailscale SSH”

What it means: Port 22 on the address you gave is Tailscale SSH, not sshd. Tailscale lets tailnet members in without checking a key, so the CLI cannot prove the key from there. It installs the key anyway, so the machine stays reachable when Tailscale SSH is off or you are outside the tailnet.

What to do: Nothing, usually. To prove the key on its own, connect to the machine’s address outside Tailscale (its LAN or public IP) with ssh -o IdentitiesOnly=yes -o IdentityAgent=none -i <key> <user>@<address>. A machine set up by an older CLI over Tailscale SSH may have no key installed at all: devmachine setup --machine <name> installs it.

setup shows a host key fingerprint that is not the one in ~/.ssh/known_hosts

What it means: Usually not a different server. A server has several host keys — ED25519, ECDSA, RSA — and the CLI asks for its own preferred algorithm, which can be a different one from the key your own ssh recorded. Two fingerprints of different types never match each other.

What to do: Compare like with like. The CLI names the type it was shown (presented ecdsa-sha2-nistp256 host key SHA256:…). Over a connection you already trust, list every key with for f in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $f; done and check the line of the same type. Only a mismatch of the same type means something changed.

--fingerprint (machines add) and --expect (machines trust) take the fingerprint of any of the server’s keys, so the one in your known_hosts works too: when it is not the type the CLI was shown, the CLI asks the server for that type, and trusts that key if it matches. A fingerprint none of the server’s keys has is still refused.

“the drop-in was written but sshd still allows passwords”

the drop-in was written but sshd still allows passwords: /etc/ssh/sshd_config.d/00-devmachine-hardening.conf is not read by this sshd

What it means: setup wrote the file that turns password login off, SSH accepted it and was reloaded, and then sshd -T — the settings SSH really runs with — still said passwordauthentication yes. SSH never reads that file. Usually the main /etc/ssh/sshd_config has no Include /etc/ssh/sshd_config.d/*.conf line, or sets PasswordAuthentication yes above it (SSH keeps the first value it finds). The CLI removed the file again and reloaded SSH, so the server is as it was: the key is installed and proved, and password login is still on.

What to do: On the server, look at the top of /etc/ssh/sshd_config. Add Include /etc/ssh/sshd_config.d/*.conf as the first line if it is missing, or remove the PasswordAuthentication yes above it. Then run setup again. To go on without hardening for now, run it with --no-harden; password login stays on until sshd_config is fixed.

I can’t SSH in with my password any more

Permission denied (publickey).

What it means: setup or machines add turned SSH password login off, and SSH has one setting for the whole machine, so it went off for every account, not only the admin login the CLI uses. On a Mac somebody uses day to day, that is their own account too. Only SSH changed: the login window, sudo, Screen Sharing and FileVault still take the password.

What to do: From this computer, which still has the admin login’s key, give the account its password back:

devmachine machines password-login <machine> --keep <account>

or put the system’s own setting back for everybody with --on (refused while the machine has ssh_hardening; remove that package first). With no flag, the command shows who can log in with a password. Without the CLI, log in as the admin login and remove the file:

sudo rm /etc/ssh/sshd_config.d/00-devmachine-hardening.conf

A Mac reads it on the next connection; on Linux, sudo systemctl reload ssh (or sshd). Next time, answer the question setup asks before password login goes off, or pass --keep-password-login. See password login, account by account.

“sshd still refuses a password for …”

the drop-in was written but sshd still refuses a password for "alice": something earlier in sshd_config decides it, so the previous drop-in was put back

What it means: the file that keeps a password for some accounts was written and accepted, but sshd -T -C user=alice still said passwordauthentication no. A Match block earlier in the main sshd_config, or another drop-in that sorts before 00-, decides it first. The CLI put back the file that was there before.

What to do: On the machine, look for Match blocks and PasswordAuthentication lines in /etc/ssh/sshd_config and in /etc/ssh/sshd_config.d/. Remove the one that turns it off for that account, then run the command again.

“Missing privilege separation directory: /run/sshd”

What it means: sshd -t, which checks the SSH configuration before it is reloaded, needs /run/sshd. systemd makes that directory only when ssh.service starts. On Ubuntu 24.04 and later sshd starts through ssh.socket, and a machine reached only through Tailscale SSH may never have started it, so the directory is not there. Nothing about the configuration is wrong.

What to do: Update the CLI and the packages release: both now make the directory before the check. Until then, sudo install -d -m 0755 /run/sshd on the machine and run the command again; the directory is temporary and gone at the next reboot.

“ansible-playbook is not on your computer”

What it means: The same check as above, for your own computer. sync and doctor both refuse to touch anything when Ansible is not on your PATH.

What to do: Run devmachine setup --machine <name>. On your own computer it runs the mac-brew package’s bootstrap (or mac-ports’s, when the machine lists it), which lists what is missing and installs it after you agree — no key, no password, no lock-down involved. See what a machine needs.

“the Mac has neither Homebrew nor MacPorts”

the Mac has neither Homebrew nor MacPorts: run again with --package-manager brew or --package-manager ports
the Mac has both Homebrew and MacPorts: run again with --package-manager brew or --package-manager ports

What it means: A Mac gets Ansible through a package manager, and the machine lists no mac-brew or mac-ports package. setup looked at the Mac (/opt/homebrew/bin/brew, /usr/local/bin/brew, /opt/local/bin/port) and found none, or both, so it cannot pick one for you, and there was no terminal to ask at. Nothing on the Mac was changed.

What to do: Choose one and run the same command again with --package-manager brew (Homebrew) or --package-manager ports (MacPorts). Or add the package yourself: devmachine packages add mac-brew --machine <name>.

“machine … lists mac-brew and mac-ports: keep one”

machine "studio" lists mac-brew and mac-ports: keep one

What it means: Both package manager packages are on the machine, and each would install Ansible its own way. setup stopped before changing anything.

What to do: Remove one from the machine’s packages: in config.yml, then run setup again.

“nothing was installed; setup stops here”

What it means: setup listed what the Mac lacks (the Command Line Tools, Homebrew or MacPorts, Ansible) and you answered no. Nothing was installed, and without Ansible the Mac cannot be synced.

What to do: Run setup again and answer yes, or install the listed items yourself and run setup again: it finds them and installs nothing.

“nothing was installed: run again with —install-prerequisites”

nothing was installed: run again with --install-prerequisites to install Xcode Command Line Tools and Homebrew

What it means: The Mac lacks the items named, and setup had no terminal to ask whether to install them. --yes does not count as that answer: it means other things, and the macOS app passes it in the background. See why consent has its own flag.

What to do: If you agree to install them, run the same command again with --install-prerequisites. Installing the Command Line Tools takes 5 to 10 minutes.

“the bootstrap stopped at …”

the bootstrap stopped at homebrew: the Homebrew installer failed; its output is above. It needs passwordless sudo for the admin login.

What it means: The package manager package’s bootstrap failed at the step it names (command-line-tools, homebrew, macports, ansible), and the rest of the message is its own advice. Steps before it are done; running setup again skips them.

What to do: Do what the message says, then run setup again. The most common cause is an admin login whose sudo asks for a password: the bootstrap only uses sudo -n.

“no mac-brew package with a bootstrap is available here”

What it means: On your own computer, setup runs the mac-brew package’s bootstrap from the package cache, and the pinned packages release has no such package (or no release is pinned).

What to do: Run devmachine packages pin to pin the latest release, then devmachine setup --machine <name> again.

“machine X is your computer (self: true), so it has no hosts”

What it means: A server marked self: true in config.yml also has hosts, user, port or key set — whichever the message names. Your own computer has no address, so it cannot carry these.

What to do: Remove the field the message names. The same error appears, one field at a time, for user, port and key.

sync on a self machine fails with “ESTABLISH LOCAL CONNECTION FOR USER: root”

What it means: Ansible asks the shell it runs in who is logged in, not your configuration. Some shells — a login shell started by a GUI app, cron, or a launcher — leave LOGNAME set to root with USER empty. Ansible believed it, looked for /var/root, and failed there instead of in your own home.

What to do: Nothing — this is fixed for you. devmachine sync on a self: true machine pins ansible_user in the generated inventory to the account devmachine itself runs as (read from the operating system, not from USER/LOGNAME), and exports the right USER, LOGNAME and HOME around the ansible-playbook run. If you still see this on a current release, run whoami and echo $HOME in the terminal you launched devmachine from, and check they say what you expect.

”… is not a usable location”

What it means: A --location flag, the answer to the location question, or a location: in config.yml has a character outside the allowed set, or is longer than 40. Capitals and spaces at the ends are fine: they are lowercased and trimmed.

What to do: Use letters, numbers, spaces, dots, underscores and hyphens, starting with a letter or number — home office, rack-2, hostinger. To go back to the default, clear it with devmachine machines edit <name> --location "".

A tailscale: address is being ignored

What it means: devmachine drops a <prefix>:<name> entry when the network package says the network is not reachable from your computer — Tailscale is not installed, not running, or does not know that name — and tries the next address instead. This is by design.

What to do: Run devmachine resolve. It lists every entry it skipped, with the reason the package gave. Then run tailscale status and check the server is listed under the name you wrote.

On a Mac with only Tailscale’s app, there is no tailscale on PATH. The CLI still finds the app’s own CLI in /Applications/Tailscale.app/Contents/MacOS, so the app being open and signed in is enough. Run /Applications/Tailscale.app/Contents/MacOS/Tailscale status to check it by hand.

“no package declares the prefix”

What it means: A hosts entry is written <prefix>:<name>, and no package in your pinned release or your own packages/ folder declares that prefix in a network: block. The entry is skipped.

What to do: Add the network package to the machine (devmachine packages add <package>) and sync, or check the prefix for a typo. For tailscale:, a packages release from before network packages still works: the CLI’s built-in resolver answers when no package does.

“the X package’s resolve did not answer within 5s”

What it means: The package’s resolve script, which runs on your computer, took too long, so its entry was skipped. The network’s own command is probably stuck: for Tailscale, tailscale status hangs too.

What to do: Run the network’s own status command. Restart its app if that hangs as well.

“joining X did not finish … run devmachine sync”

What it means: devmachine login <package> ran the package’s join script on the machine, and it failed. The most common reason is that the package is not on the machine yet: join runs from where sync put it. Otherwise, the script’s own output, above the error, says what went wrong.

What to do: devmachine sync, then devmachine login <package> again.

ssh <workspace>-devmachine says “no address answered” or “Connection closed by UNKNOWN”

What it means: The alias connects through devmachine ssh-proxy, and none of the machine’s addresses accepted a connection. ssh shows the proxy’s error, which lists every address and why.

What to do: Run devmachine resolve to see which addresses were tried. If it says devmachine: command not found instead, the CLI moved since the alias was written: run devmachine aliases --write again.

devmachine ssh <workspace> on a Mac ends with “exit status 255” and “Remote Login may not allow”

exit status 255: the Mac's Remote Login may not allow alice; `devmachine doctor --machine studio` checks it

The Mac’s own log (log show --predicate 'process == "sshd"' --last 5m) says pam_sacl: denying 'alice' due to failed service ACL check.

What it means: Remote Login on that Mac is set to “Only these users”, and the workspace account is not on the list (the group com.apple.access_ssh). macOS refuses the login before it checks the key, so ssh only sees the connection close. The CLI adds this hint only for a machine it last saw as a Mac; exit 255 has other causes too, such as an address that does not answer.

What to do: Run devmachine doctor --machine <name>. An ssh access: <workspace> warning confirms it. Run devmachine sync, which adds each workspace account to the list, or, on the Mac, choose “All users” in System Settings > General > Sharing > Remote Login. See what a machine needs.

devmachine run exits 255

What it means: The command never ran: run could not find the machine or workspace, could not connect, found a changed host key, or the package is not installed there. The line after error: says which. ssh uses 255 for the same thing, so a script can tell it apart from the command’s own failure. A command that exits 255 by itself, or that was stopped with Ctrl-C or SIGTERM, also ends with 255.

What to do: Read the error: line. For a connection, devmachine doctor --machine <name> checks the way in.

“with —argv, the program and its arguments follow --”

What it means: With --argv, everything after -- is the program and its arguments. Without --, the arguments would be read as flags of devmachine itself.

What to do: devmachine run --argv -- df -h /.

“—script ”…” names a file inside the package” or ”… has no file …”

What it means: run --package <name> --script <path> runs a file of that package, relative to its package.yml. A path that leaves the package (../, or starting with /) is refused before anything connects, and run exits 1. “has no file” means your copy of the package does not have that file, so the machine’s copy, which sync made from yours, does not either.

What to do: Use the path as it appears inside the package folder, for example widgets/disk/check.sh. If you just added the file, run devmachine sync so the machine gets it.

doctor says an alias has “a fixed address, expected one resolved when ssh connects”

What it means: The alias was written with the address itself, by an older version or while devmachine was not on your PATH. It works until that address stops working.

What to do: devmachine aliases --write. See SSH aliases that resolve when you connect.

doctor says skip ssh aliases managed outside devmachine (ssh_aliases: false)

What it means: config.yml does not have ssh_aliases: true, so devmachine does not keep your SSH aliases. You manage ~/.ssh/config yourself, and doctor does not judge a file it did not write. Nothing is wrong.

What to do: Nothing, if you keep ~/.ssh/config on purpose. To have devmachine keep the aliases and check them, run devmachine aliases --write once and say yes. See SSH aliases.

doctor exits non-zero, but most machines say pass

What it means: With several machines, doctor checks all of them and exits non-zero when any one has a fail. The error names which ones, for example some checks failed on far.

What to do: Look at that machine’s block, or run devmachine doctor --machine far to see only its checks.

“package X runs on linux; machine Y is macos”

package "firewall" runs on linux; machine "studio" is macos

What it means: The package’s package.yml lists the systems it runs on under platforms, and the machine’s system is not one of them. sync (and update, which syncs) stopped before changing anything on the machine. The machine’s system is what setup, sync or doctor last read from it — devmachine machines show <name> prints it — and sync checks again on what it reads as it connects. The reverse, runs on macos; machine … is linux, is the same stop for a Mac-only package on a Linux server.

What to do: Take the package off that machine or workspace with devmachine packages rm <package> (add --workspace <name> for a workspace package), then sync again. If the package is your own and does run on that system, add the system to its platforms. If the machine was rebuilt with another system, run devmachine doctor --machine <name> so the CLI reads it again.

devmachine packages add and devmachine workspaces edit --add stop the same mistake up front, with package "docker" runs only on linux and machine "studio" is macos, so it was not added; nothing is written. devmachine workspaces new leaves such a package out of the default list and says so, and refuses it in --packages with leave it out of --packages. A package can also be refused because of one it needs: needs systemd-unit, which runs only on linux. Both check only once the machine’s system is known, so a list written before that can still reach sync with a package that does not fit.

A Mac added by an older CLI may list essentials, which runs only on Linux. Swap it for what a new Mac starts with: devmachine packages rm essentials --machine <name>, then devmachine packages add base --machine <name> and devmachine packages add devmachine-app --machine <name>.

packages validate warns about devmachine_account

warning: notes/defaults/main.yml:2: reads devmachine_account, but no task in this package registers it. …

What it means: The package uses devmachine_account (a workspace account’s home or group), but none of its own tasks sets it. Ansible keeps a registered variable after the role that set it ends. So this package reads the account the previous package left, which on a machine with several workspaces can be another workspace’s. Files then land in the wrong home, or get the wrong group. On a machine with one workspace it looks fine, which is why it can go unnoticed. It is a warning, not an error: validate still passes and sync still runs.

What to do: Add this as the first task of the package’s tasks/main.yml, as the upstream packages do:

- name: Read the account's home and group
  ansible.builtin.user:
    name: "{{ devmachine_workspace.user }}"
  check_mode: true
  changed_when: false
  register: devmachine_account

It only reads the account and never changes it. See one package on many systems.

A setting is accepted, but the package still uses its default

What it means: A setting reaches the server as devmachine_<package>_<name>, with dashes and dots turned into underscores. If the package reads a different variable name, your value arrives but nothing looks at it.

What to do: See what was actually sent:

devmachine run --machine main -- "cat /opt/devmachine/host_vars/devmachine.yml"

If your variable is there under a different name than the package’s own defaults/main.yml uses, the package needs fixing — the name in its defaults is the name a setting has to match.

machines edit or workspaces edit says it “does not install the package”

What it means: The setting’s first part, before the dot, names a package that machine or workspace does not have. Nothing would read the value: the role would keep its default, so the CLI refuses it instead. It is usually a typo in the package name, or a package added to the workspace when the setting is on the machine (or the other way round).

What to do: Check the name with devmachine packages list. If the package really is missing, add it first (devmachine packages add <name> --machine main), then set the value.

devmachine ssh opens a session as the wrong user

What it means: devmachine ssh with no argument logs you in as the server’s root account, not a workspace.

What to do: Name the workspace: devmachine ssh acme.

Changes to config.yml appear to be ignored

What it means: devmachine may be reading a different file than you think.

What to do: Check which one:

devmachine config path

DEVMACHINE_CONFIG in your shell beats the default location, and a --config flag beats everything.

secrets list shows nothing after storing one

What it means: The list of names lives in your configuration folder, even though the values themselves live in your keychain.

What to do: Check you are using the same configuration folder you used when storing it — see devmachine config path above.

secrets set --env-file refuses the path

What it means: --env-file takes a path relative to the workspace’s own home, and the one given would land outside it — an absolute path (/etc/passwd), or one with enough ../ to walk out of the home directory.

What to do: Give a path inside the workspace, such as app/.env or .env. There is no way to deliver a workspace secret outside that workspace’s own home.

What it means: The path looked fine on your computer, but on the machine one of its directories — or the file itself, or its .devmachine.bak — is a symbolic link that points outside the workspace’s home. The path is either the --env-file of a workspace secret, or where a package delivers a workspace credential (~/.devmachine/<name>/env, or the package’s own path). The push runs as the machine’s admin, and the workspace’s own account can create links anywhere in its home, so following one would let that account aim a root write at any file on the machine. The push stops before it reads or writes anything.

What to do: Look at the path on the machine (ls -la each directory on the way). If the link is yours and meant, point --env-file at the real file inside the home instead, or replace the link with a real directory or file. If nobody in the workspace made it, treat it as a warning about what runs in that workspace. A link that stays inside the home is followed as usual.

What it means: A login shared across workspaces (such as gh or git-key) lands at its stored_at path in each workspace’s home. In the named account’s home, one directory on that path, or the file itself, is a symbolic link that points outside the home. The copy runs as that account, never as root, so the link could never have let it write a file the account could not already write. But a login copied to some other place would be lost or leaked, so sync stops at that account instead. Nothing is written there, and nothing outside the home changes.

What to do: Look at the path in that workspace (ls -la each directory on the way, then the file). Replace the link with a real directory or file, or remove it, and run sync again. If you want that workspace to keep a login of its own, opt it out with devmachine workspaces edit <name> --share <login>=own. If nobody in the workspace made the link, treat it as a warning about what runs in that workspace. A link that stays inside the home is followed as usual.

A workspace secret was pushed, but the app never sees it

What it means: devmachine credentials push writes the value into ~/.devmachine/env (or the --env-file you gave), but nothing runs that file for you — that is the shell’s job, not the CLI’s.

What to do: For the default ~/.devmachine/env, check the workspace’s shell actually sources it: the workspace package loads it through ~/.devmachine/shellenv, which zsh, bash and sh all read, from packages v37 on. Run devmachine sync if the machine is on an older packages release. For --env-file, check the app reads that exact file and reloads its process after the value changes — this only writes the file, it does not restart anything running.

dns status says a name does not resolve, but it works in the browser

What it means: The check runs from your computer, not the server, and it ignores your browser’s cache and any proxy you use. A name that works in the browser but not here usually means DNS has not finished propagating everywhere, or something local — a VPN, an /etc/hosts entry — is resolving it just for you.

What to do: Wait a few minutes and check again, or check your own network settings for something overriding DNS.

dns add/dns rm/dns list/dns check fail with one of these

Every DNS provider reports one of a fixed set of errors, shown here in plain words:

ErrorWhat it means
zone not found, or the token cannot see itThis domain does not exist under this provider, or your token cannot see it.
the token was rejectedYour credential is wrong or expired. Store the new one with devmachine secrets set and run devmachine credentials push: it replaces the old copy on the machine. On Hostinger, a 403 before packages v26 was the provider itself, not your token — see below.
the token cannot change this zoneYour token can read the domain but not write to it.
the record was rejectedThe registrar refused the value — a bad type, a bad value, or a name it will not accept.
rate limitedThe registrar’s API is temporarily blocking this token from making more requests. devmachine never retries this on its own; wait and run the command again.
this record type is not supported yetThe types are A, AAAA, CNAME, TXT, MX, SRV, NS and CAA. SOA belongs to the registrar.
the value does not fit the typeThe value was refused before any provider was asked: an MX is <priority> <host>, an SRV <priority> <weight> <port> <target>, a CAA <flags> <tag> <value>, an A an IPv4 address. The message says which part is wrong.
the installed provider cannot add a value next to the ones a name holdsThe provider package on the machine predates dns add --append. Run devmachine update to get one that accepts append, or leave out --append to make the name hold just this value.
the name holds several valuesTwo installed providers both claim this domain. Say which one with --dns-provider.

Two more lines that are not errors, but change what a command does:

  • “no installed provider holds this zone” — none of the providers you have installed recognized this domain. This is normal for a registrar with no devmachine package yet: the command falls back to manual and prints the record for you to create by hand.
  • “no DNS provider is installed” — the machine has no DNS provider package at all, so the record is printed. devmachine packages list shows the providers you can add.
  • ”… could not be reached, so no DNS provider on it was asked” — a provider runs on the machine, so with the machine down nothing can be written or removed, and the record is printed instead. Once the machine answers, devmachine dns add or devmachine dns rm does it for you.
  • “the provider failed”, with something that looks like a crash — this is a bug in the provider package, not in devmachine itself. The package sent back something that does not match the DNS provider contract.

Hostinger answers every call with HTTP 403, but the token works with curl

What it means: Before packages v26, the hostinger provider sent Python’s default User-Agent, and Hostinger’s firewall answers that with a 403 — the same status a token without DNS access gets. Every dns command said the token was rejected, and expose add fell back to printing the record by hand.

What to do: devmachine packages pin v26 (or later) and devmachine sync --tags hostinger. A token without “Domains portfolio” permission also needs the zones listed: devmachine machines edit main --set hostinger.zones=[example.com].

GoDaddy answers 403 ACCESS_DENIED to every command

What it means: GoDaddy does not allow the account on its Domains API. It is not the token. GoDaddy lets only accounts that hold a domain, or a plan with management access, call it, and answers every other call with 403 ACCESS_DENIED.

What to do: Ask GoDaddy directly:

curl -H "Authorization: Bearer $PAT" https://api.godaddy.com/v1/domains

A 403 there is GoDaddy’s account rule, and a new token will not change it. A 200 with an empty list means the account has no ACTIVE domain, so devmachine dns providers shows no zone.

expose add said “the DNS record for … was not written”

What it means: The site is on Caddy, but the DNS provider refused the record; the reason is on the same line. Until the record exists, visitors cannot find the site and Caddy cannot get its certificate.

What to do: Create the record the command printed, or fix the provider (see the table above) and run devmachine dns add <name> A <address>.

expose rm or workspaces destroy said “the DNS record for … was not removed”

What it means: The site is off Caddy, but the record that pointed the name at the machine is still there: the DNS provider could not list the zone, refused the delete, or its setup is broken; no DNS provider is installed, or the machine could not be reached to ask one; or the name also points at another address, and taking one value out of several is left to you. The reason is on the same line. The name still resolves, and visitors get a TLS error instead of nothing.

What to do: Remove the record the command printed, or fix the provider (see the table above) and run devmachine dns rm <name> A <address>.

expose rm or workspaces destroy says a name “points at …, not at …: its DNS record is left alone”

What it means: The name’s A record no longer holds the serving machine’s address, so expose rm did not touch it. Somebody repointed the name after expose add, maybe at a new server.

What to do: Nothing, if the new value is right. If the name should go, remove it with devmachine dns rm <name> A <value>.

A certificate never arrives after expose add

What it means: First check devmachine expose list: a pending site never reached Caddy (the machine was out of reach, or --no-apply was used), and devmachine sync publishes it. A published site is on Caddy, and Caddy (the reverse proxy) only gets a certificate for a name that already points at the server. Two common causes:

  • The name does not resolve yet. DNS can take a few minutes to catch up, even if expose add already wrote the record (or printed it for you to add by hand). Caddy keeps retrying on its own; devmachine dns status <host> tells you when it has caught up.
  • Caddy has not noticed the new site yet. It watches for changes, but can miss one on a busy server.

What to do: Wait for DNS, or force Caddy to reload:

devmachine run --machine <name> -- 'systemctl reload caddy'

expose add says “caddy refused the new … routes file, so the old one stays”

What it means: The route is in config.yml, but caddy validate refused the whole configuration with the new file in place, so nothing on the machine changed and Caddy serves what it served before. The lines after the message are Caddy’s own words. Two common causes:

  • Another file in sites.d already names the host. Caddy refuses one host in two files. devmachine expose list shows it as unmanaged; remove that file, or drop this route and adopt the other one.
  • The configuration was already broken by a file that has nothing to do with this route — something written by hand, or by a package. Caddy checks everything, so any broken file stops the new one.

What to do: Fix what Caddy names, then run devmachine sync — the route is still recorded as pending. devmachine expose rm <host> drops it instead.

expose add says the route is pending

What it means: The route is in config.yml, and the machine does not serve it yet. The message says why: the machine could not be reached, or caddy is in the configuration but not installed there yet. It is not an error, so the command still succeeds.

What to do: devmachine sync when the machine is back, or once more to install caddy.

expose add --via says “no address of … another machine can reach”

What it means: The machine with Caddy has to reach the workspace’s machine, and every address that machine has is a loopback one, such as the 127.0.0.1 a local VM starts with. Only your computer can use that address.

What to do: Put the machine on your private network and run devmachine login tailscale --machine <name>, which adds its tailscale: name to hosts. Your own computer must be on that network too, since that name is resolved there. See share an app on your computer with friends.

expose add served, and the response is “Blocked request”

What it means: This is your application’s own check, not Caddy and not expose. Many frameworks refuse a Host header they do not recognize by default, as a safety guard — and a name you just published is exactly the kind of header the app has never seen before.

What to do: Add the published hostname to your application’s own list of allowed hosts. expose has nothing to do with that list.

A sync cannot fetch the release

fetching https://github.com/.../packages-v1.tar.gz: the server answered 404

What it means: The pin in config.yml names a release that does not exist.

What to do: Check packages: in your configuration against the tags the packages repository actually has — a pin is a release tag, never a branch. If the URL looks right, the problem is your network: this is a plain anonymous download, so a proxy or firewall that blocks GitHub blocks this too.

Once a release is downloaded, it is cached — a later sync at the same pin needs no network at all.

“the asset changed, which a pin exists to prevent”

What it means: The file downloaded does not match the checksum the release published. devmachine refuses it and stops, rather than send it to your server.

What to do: This means the release was changed after it was published, or something altered it in transit. Get the release fixed, or pin a different one.

update says “package release v34 has no package named “devmachine-skills""

==> 3/3 Skills
  failed: package release v34 has no package named "devmachine-skills"

What it means: Usually not that the release lacks the package. Before 0.7.32, two devmachine commands that downloaded the same release at the same moment could delete each other’s copy. update pins the new release and then downloads it for the skills step, while the Mac app runs packages list on its own. The command that finished second removed the release the first one was reading, so the package seemed missing for a moment.

What to do: Run devmachine skills update --yes. The pin has already moved, and the release is now complete in the cache. From 0.7.32, each download works in its own folder and never removes a complete release, so the first one to finish is the copy every command uses.

If the error comes back, the release really lacks the package: check devmachine packages list.

“package X needs a CLI >= 0.3.0, and this one is 0.2.1”

What it means: The package says which CLI version can read it, and yours is older.

What to do: Upgrade: brew upgrade devmachine. Or pin an older release of the packages instead, if upgrading is not your call to make.

“package X is a workspace package, and main is a machine”

What it means: Some packages belong on a server (shared by everyone, like Docker); others belong to one workspace (like Claude Code, which needs its own sign-in per person). You tried to add this one in the wrong place.

What to do: Use the command the error shows, for example:

devmachine packages add claude-code --workspace acme

“package X extends caddy.sites.d, but caddy is not installed on machine main”

What it means: This package adds files into a place another package manages, so that other package has to be on the same server.

What to do:

devmachine packages add caddy --machine main

The same error appears if the package is installed but does not declare that it provides that place — check its provides: against the extends: that names it.

A file a removed package left behind is still on the machine

What it means: sync only removes a file it remembers writing — see What sync removes. If a package was removed from your configuration before you upgraded to the version that started tracking this, sync never recorded that file, so it never cleans it up.

What to do: Find it under the directory the extending package used (sites.d for Caddy) and remove it by hand:

devmachine run --machine <name> -- 'rm /etc/caddy/sites.d/<package>-<file>'

Then reload Caddy, if it is on the server:

devmachine run --machine <name> -- 'systemctl reload caddy'

sync --check fails on a machine nothing has been applied to yet

A dry run against a server with no packages applied yet reports failures like:

No package matching 'docker-ce' is available
Could not find the requested service caddy: host

What it means: Nothing is actually wrong. A dry run changes nothing, so a package’s software repository is never really added, and the package it would have provided genuinely is not there to look at yet.

What to do: Run devmachine sync for real once. After that, --check is meaningful, because there is something on the server to compare against. Use a dry run to preview a change to a server you already built — not to preview the first build itself.

“another sync is running on …: wait for it to finish, then run this again”

What it means: Another sync or sync --check holds this machine right now. It can be one in another terminal, one from another computer, or the app’s Prepare button. Two runs at once would delete each other’s files on the machine, so the second one stops before it changes anything.

What to do: Wait for the other run to end, then run yours again. The lock clears itself when that run ends, when its connection drops, and after a reboot, so there is nothing to remove by hand. See one sync per machine.

sync --check fails on a skill with “getgrnam(): name not found: ‘1001’”

A dry run stops on a task like global-skills installs the workflow skill, with KeyError: "getgrnam(): name not found: '1001'", and a real sync of the same machine passes.

What it means: The machine has an older Ansible (ansible-core 2.16, the Ubuntu 24.04 package). Its copy module looks a folder’s group up by name in a dry run only, and devmachine gives the workspace’s group as a number, because a Mac has no group named after each account. CLI versions 0.8.0 to 0.10.0 have this problem.

What to do: Update the CLI. From v0.10.1 a dry run leaves that one group out, so it does not report group changes on a skill’s files. A real run still sets the group.

sync asks and I answered nothing

What it means: An empty answer counts as no, and so does closing the input. A command that changes a server defaults to changing nothing.

What to do: Pass --yes to skip the question, or --check to see what would happen without being asked at all.

expose add --yes or dns add --yes says “nothing was changed”

What it means: --yes only skips questions about files on your computer. It never says yes to putting something on the internet, so the publish question was still asked. In a script or a pipe nobody answered, an empty answer counts as no, and the command stopped. It exits non-zero so a script does not take “I did not do it” for “done”.

What to do: Pass --publish to expose add or dns add when the command runs without a person to ask. --check shows what it would do first.

ERROR! Invalid options for include_role: devmachine_<package>_<name>

What it means: This was a bug in how devmachine generated its internal Ansible playbook, and it is fixed. If you see it, your binary predates the fix.

What to do: Build or install a newer devmachine. Nothing on the server was changed — the run stopped before it started.

credential "X" cannot be shared

What it means: You asked to share this login (X: machine), but the package that declares it says it cannot be — usually because the tool’s session file is tied to one device or browser, and a copy of it would not work anywhere else.

What to do: Ask for own instead, and sign in once in each workspace. If you know a copy really does work for that tool, the fix belongs in the package: add shareable: true to its declaration.

The shared login did not reach a workspace

What it means: Two common reasons, in this order:

  • Nobody has signed in yet. The copy comes from a login already stored on the server, and sync skips a workspace rather than fail when there is nothing to copy.
  • That workspace keeps its own login. A workspace with <name>: own in its credentials: is deliberately left out of the copy, so it never loses the account it signed in with.

What to do: Run devmachine login <name> then devmachine sync --tags credentials, or remove the own line if you meant to share after all.

credentials list says unknown

What it means: The package never said where its tool keeps this login, so devmachine has nowhere to look. The login may well be there.

What to do: Add stored_at: to the package’s declaration, and the row starts giving a real answer.

“credential X belongs to a workspace: name it with —workspace”

What it means: Two workspaces sign in to the same tool with different accounts, so “where do I log in” has no single answer.

What to do: Name the workspace. The list in the error shows every workspace that uses it.

“the connection dropped after part of the input was sent”

A machine with several addresses in hosts: is normally tried one address after another until one answers. That is safe only while nothing has been sent yet. This error means the first connection took part of a file or a secret and then dropped. Sending the rest to the next address would leave a cut-off file on the machine, so the CLI stops instead.

Run the same command again. If one address keeps dropping, move the stable one first in hosts:.

The SSH host key is not trusted

What it means: Configurations made by v0.6 and earlier have no stored server identity. devmachine will not learn one silently.

What to do: Run devmachine machines trust <machine>, compare the fingerprint it shows with your provider’s dashboard or another source you trust, and approve it. This command reads the key without logging in.

The SSH host key changed

What it means: Something about the server no longer matches what devmachine trusted before. This can mean a deliberate rebuild, a configuration mistake, or an attack — devmachine cannot tell which, and will not connect until you decide.

What to do: Run devmachine machines trust <machine> --check. It reads the presented key without logging in, writes nothing, and prints both fingerprints, a command to print the same key on the server, and the fix. Run that command from the machine’s own console — the provider’s web console, or limactl shell on the Mac that runs a Lima VM — never through the SSH connection you are trying to verify. If the fingerprints match, run devmachine machines trust <machine> --replace. --yes skips confirmation — that never substitutes for --replace.

run can keep working for up to five minutes after the key changes. It reuses the connection it opened last time, which was checked when it was opened and still goes to the same server. The first new connection after that checks the key again and stops with this error.

The host key changed after restarting a Lima VM

What it means: Usually nothing bad. Lima hands the VM a new cloud-init instance ID (iid-<time>) on every limactl start, so cloud-init treats each boot as a new instance and, by default (ssh_deletekeys), deletes the SSH host keys and writes new ones. Restarting the VM — to change its memory or CPUs, or for any other reason — gives it a new host key. The disk, the users and the Tailscale address stay the same. A different local network address underneath Tailscale does not matter either: the key is pinned to the machine’s name, not to an address.

What to do: Check the fingerprint from the Mac that runs the VM, with limactl shell <instance> — a local path to the VM, not the network path you are trying to verify — and compare it as in The SSH host key changed. The files under /etc/ssh/ssh_host_* carry the time of the last boot. Then replace the key.

To keep the keys across restarts, tell cloud-init not to delete them, on the VM:

echo 'ssh_deletekeys: false' | sudo tee /etc/cloud/cloud.cfg.d/99-keep-host-keys.cfg

The next restart keeps the key you trusted.

machines trust --expect says “presented …, not the expected …; nothing was written”

What it means: machines trust reads the key again each time it runs, and the key it got now is not the one you checked and passed to --expect. The server changed its key between the two runs — a rebuild, or a Lima VM restarted in between — or this run reached a different server. devmachine writes nothing rather than trust a key you did not check.

What to do: Run devmachine machines trust main --check again and compare the new fingerprint from the machine’s own console, as in The SSH host key changed. Pass the new fingerprint to --expect only if it matches.

The SSH trust file is malformed

What it means: The error names <config>/known_hosts and the bad line. This file may hold entries for other servers too, so do not delete the whole thing.

What to do: Fix that one line, or remove just that server’s entry, then run devmachine machines trust <machine> to approve it again. The file uses plain OpenSSH known_hosts syntax.

login says “the login did not finish: exit status N”

What it means: login opens a plain ssh session on the machine and runs the tool’s own sign-in command there. The number is how that session ended:

  • 255 — ssh itself failed: the machine did not answer, or it refused the key. The tool’s sign-in never started.
  • Any other number — the sign-in command ran and exited with that code: you cancelled it (Ctrl-C), or the tool failed. Its own message is above this line.

What to do: For 255, run devmachine doctor --machine main; it says whether the machine answers and takes the key. For any other number, read the tool’s message above and run devmachine login <credential> again.

“the login left nothing at …”

What it means: The login command ran, but the file the package promised is not there. Either the sign-in was cancelled, or the tool actually stores its session somewhere else than the package says.

What to do: Check where the tool really writes its session, and fix the package’s stored_at.

credentials push says “nothing to deliver” and the value is out of date

What it means: An env file push delivered itself is replaced when its value changed (replaced). A file a tool keeps for itself (path: in the package) is never rewritten once it is there, so the server keeps the old value.

What to do: Remove that file on the server first — its path is in devmachine credentials list — then push again.

I already committed a key

What it means: Removing a file from git’s index is not enough. It stays in every past commit — anyone with a clone, or the history itself if the repository is ever made public, can still find it.

What to do:

  1. Rotate the key first. Generate a new one and get it authorized wherever the old one was, so the copy in your history stops being able to get in anywhere.
  2. Then untrack it: git rm --cached <path>, commit that, and add it to .gitignore if devmachine setup git had not already.
  3. If the repository was ever pushed anywhere, rewriting history (with git filter-repo, or by deleting and recreating the remote) removes the key from what other people can see — but it was compromised the moment it was committed, whatever you do to the history afterwards. Step 1 is the one that actually fixes anything.

devmachine setup git refuses to run against a directory that already tracks one of these paths, and says so — see versioning your configuration.

expose add said “recorded”, and the site does not answer

What it means: add only writes to your configuration. The change reaches Caddy on the next devmachine sync.

What to do: Run devmachine sync, then devmachine expose list should say published.

expose list says unmanaged

What it means: The server has a site your configuration does not know about — written by hand, or by an old version of expose. It works today, but is lost the day the server is rebuilt.

What to do: Run the expose add the row prints, to adopt it. After that, sync writes the workspace’s own file and removes the old one, so Caddy sees the host only once.

expose list says differs

What it means: Your configuration and the server disagree on the port or the owner of a host.

What to do: Run devmachine sync — your configuration is treated as the source of truth, and the server is made to match it.

“workspace X publishes Y, but caddy is not on machine Z”

What it means: This route has nowhere to go.

What to do:

devmachine packages add caddy --machine Z
devmachine sync

“caddy is not on X, where Y lives: publish it through a machine that has caddy”

What it means: The workspace’s machine has no Caddy, and another machine in your configuration does. expose does not pick one for you.

What to do: Publish through the machine it names:

devmachine expose add Y <port> --host <host> --via <machine>

Adding caddy to X instead only helps when the internet can reach X.

expose add --via warns “edge cannot reach lab at …”

What it means: The site is on Caddy, but the machine serving it could not open a connection to the port on the workspace’s machine. Visitors get a 502 until that changes.

What to do: On the workspace’s machine:

  • The service must listen on the address the warning names, or on every address — not only on 127.0.0.1. A container published as 127.0.0.1:8080:80 cannot be reached from another machine.
  • A firewall must let the serving machine in on that port.
  • Both machines must be on the private network the address belongs to: devmachine resolve --machine <machine> shows which address is used.

Nothing needs publishing again: Caddy retries on every request.

sync says ”… is left as it is on edge, since lab’s address is not known”

What it means: The private network that gives the workspace’s machine its address is off or signed out on your computer, so the file on the serving machine could not be written. It was left exactly as it was, and the site keeps answering the way it did.

What to do: Turn the network on here and run devmachine sync again. devmachine resolve --machine lab shows why the address is missing.

sync failed at “reload caddy for the routes”

What it means: Caddy refused the new set of site files. The most common cause is the same host named in two files — one from another package, or one written by hand — as one the configuration also publishes.

What to do: Find the duplicate:

devmachine run 'caddy validate --config /etc/caddy/Caddyfile'

Remove it from whichever side should not own that host.

workspaces destroy failed at userdel

On a Mac the step is sysadminctl -deleteUser, as macOS has no userdel; the same applies. Before it, destroy takes the account out of com.apple.access_ssh, the group Remote Login uses when it allows only some users, so no stale entry stays behind.

What it means: Something is still running as that account — a process started outside its login session, or a container. destroy already disabled the account and stopped everything it could find, but something outlived that. Your configuration was left untouched, so you can retry.

What to do:

devmachine run "ps -u <user>"

Stop what is listed, then run devmachine workspaces destroy <name> again.

workspaces destroy refuses: “destroying the account would leave Caddy serving it”

What it means: The workspace publishes a site, and destroy could not take it off Caddy first. Without that step the account would go, and Caddy would keep serving the name to a port nobody owns. The message says which case it is:

  • “the file that serves it cannot be found” — devmachine could not work out where Caddy keeps its site files: caddy is no longer in the machine’s packages, or the packages could not be read. The reason is in the brackets.
  • “through edge, which could not be reached” or “whose Caddy cannot be found” — the site goes through another machine (--via edge), and that machine did not answer, or has no Caddy now.
  • “taking alice’s sites off edge: …; nothing was destroyed” — edge answered, but removing the site failed there.

Nothing was destroyed in any of these cases.

What to do: Once the machine answers, run devmachine workspaces destroy alice again. If Caddy is really gone, devmachine expose rm app.example.com each site and devmachine sync first.

workspaces rm says it “would keep serving it with nothing left to take it off”

What it means: The workspace publishes a site through another machine (--via edge). The route lives in this workspace’s entry, so forgetting the workspace would also forget the route — while edge keeps serving the name, with no command left that knows to remove it.

What to do: devmachine expose rm app.example.com first, then devmachine workspaces rm alice.

machines rm says a machine “still serves … for another machine”

What it means: Another machine’s workspace publishes a site through this one (--via). Forgetting this machine would leave its Caddy serving the name, with nothing in the configuration that points at it.

What to do: devmachine expose rm app.example.com for each name the message lists, then devmachine machines rm edge.

run hangs, or answers with a login from a machine that no longer exists

What it means: run keeps its SSH connection open for five minutes and reuses it (see the run reference). If the server it was talking to changed address, was rebuilt, or was deleted, that old connection can be left open and never answer again.

What to do: Close it. The connection lives in a socket file in <user cache dir>/devmachine/cm/ — or in /tmp/dm-<uid>/ when that path would be too long (see the next section). Its name is the first 16 characters of the SHA-256 of <user>@<address>:<port>:

name=$(printf '%s' '<user>@<address>:<port>' | shasum -a 256 | cut -c1-16)
ssh -O exit -o ControlPath=<that directory>/$name <user>@<address>

If you do not have the exact address, delete the stale socket file directly from that directory instead. Either way, the next run opens a fresh connection.

“unix_listener: path … too long for Unix domain socket”

Shown as machine "x": the file ssh shares one connection through, …, makes a path longer than this system allows for a socket, or in older versions as no address answered: … (unix_listener: path "…" too long for Unix domain socket).

What it means: run and the other short commands share one SSH connection through a socket file. A socket’s full path has a size limit set by the operating system: 104 bytes on macOS, 108 on Linux. While ssh creates the socket it adds 17 more characters to the name. With a long home folder, the path went over the limit, and ssh gave up before it connected. Nothing is wrong with the machine or the network.

Versions after 0.7.27 use a 16-character name, and when even that does not fit under your cache directory they use /tmp/dm-<uid>/ instead. So on a current version you should not see this. If you do, it is a bug: report it with the path from the message.

What to do: update devmachine (devmachine update). If it then says /tmp/dm-<uid> “is owned by another account” or “has mode …”, that folder is not safe to hold your connections: remove it (or chmod 700 it if it is yours) and try again.

upload refuses a file or a folder

What it means: one of these, checked on your computer before anything connects, or on the machine before anything is written:

  • “is a folder: upload sends files” — upload sends single files. Send an archive instead (tar czf notes.tgz notes) and unpack it with devmachine run.
  • “no such file or directory” or “cannot be read” — the path is wrong, or your account cannot read that file.
  • “—dir … reaches outside the home” or “is outside the home” — the folder climbs out with ../, or is an absolute path in another home. upload only writes inside the home of the account it sends to.
  • “reaches outside the home through a symbolic link” — the folder, or one on the way to it, is a link to somewhere outside the home. Following it would put the file wherever the link points.
  • “is not a folder” — a file sits where the folder should be.

With several files, the others are still sent; only the refused ones are missing, and the command exits non-zero.

What to do: Pick a folder inside the home (the default, ~/.cache/devmachine/uploads, always works), or replace the link on the machine with a real folder.

download refuses a path

What it means: one of these, checked on your computer before anything connects, or on the machine before anything is written here:

  • “—to … no such file or directory” or “is not a folder” — the folder you named with --to does not exist on your computer. download never creates it, so a typo cannot scatter files somewhere new.
  • ”… does not exist” — the path is wrong, or it sits inside a folder the account cannot enter, which looks the same from that account. A relative path starts at the home of the account that reads it: the workspace’s with --workspace, the admin’s without.
  • ”… cannot be read” — the file is there, but the account that reads it has no permission. Read it as another account (drop --workspace to read as the admin), or change its permissions on the machine.
  • ”… is not a regular file” — a device, a socket or a pipe. Only files and folders can be downloaded.
  • ”/ is the whole disk” — name a folder inside it instead.
  • “reading … : tar: …” — a folder was packed, but tar could not read something inside it, usually a file the account has no permission for. The archive is dropped rather than saved incomplete.

With several paths, the others are still downloaded; only the refused ones are missing, and the command exits non-zero.

What to do: Check the path with devmachine run --workspace <w> -- ls -la <path>, which reads as the same account.

run --package fails with “exit status 127”

What it means: the machine has no file at the entrypoint path. The CLI builds that path from your configuration, the way sync does: a package in your own packages/ directory runs from /opt/devmachine/roles.local/<name>, and one from the release runs from /opt/devmachine/roles/<name>. If you added or removed a local copy since the last sync, the CLI looks in one directory and the machine still holds the package in the other.

What to do: Run devmachine sync, so the machine matches your configuration again.

“no package named X, and none is available”

What it means: Either the name is wrong, or no packages release is pinned. With no packages: line in config.yml, only your own local packages exist.

What to do: Run devmachine packages pin, which pins the latest release, then devmachine sync. A configuration made by setup from version 0.7.7 on is already pinned.

update says “checksum mismatch for devmachine_…tar.gz”

What it means: The archive that arrived is not the one the release published — a proxy rewrote it, the download broke half way, or something is in between you and GitHub that should not be. Nothing was replaced: the new file is checked before anything is written, and your CLI is exactly as it was.

What to do: Run devmachine update again. If it keeps failing, install by hand with curl -fsSL https://mydevmachine.sh/install.sh | sh, which checks the same checksum, from another network.

update --cli-only says ""dev” was built from source”

What it means: This devmachine was built from the source code, not installed from a release, so it has no release version and no install that update could replace. Plain update skips the CLI step for such a build; --cli-only has nothing else to do, so it fails.

What to do: Build it again from the source (git pull && make build), or install a release with curl -fsSL https://mydevmachine.sh/install.sh | sh and remove the built copy from your PATH.

update says “replacing …: permission denied”

What it means: The CLI lives in a folder your user cannot write, such as /usr/local/bin, so the new version could not be put in its place. Nothing was replaced.

What to do: Reinstall it where you can write, with curl -fsSL https://mydevmachine.sh/install.sh | sh (it installs to ~/.local/bin), and remove the old copy. Running update with sudo would also work, but then the rest of the update runs as root, with root’s configuration.

”… was installed by Homebrew, but brew is not on PATH”

What it means: The CLI’s real file is inside Homebrew’s Cellar, so only Homebrew should replace it — and update could not find brew to ask.

What to do: Put Homebrew on your PATH (eval "$(/opt/homebrew/bin/brew shellenv)" on Apple silicon), or run brew upgrade mydevmachine/tap/devmachine yourself, then devmachine update --skip-cli.

update says “still 0.7.17 after the upgrade”

What it means: The upgrade finished, but the binary that started next is the same version. Usually Homebrew did not know the new release yet, or another devmachine earlier on your PATH is the one that ran.

What to do: Run which -a devmachine to see every copy. Remove the ones you do not use, then brew update && brew upgrade mydevmachine/tap/devmachine or the install script.

doctor says warn credential: gh missing

What it means: A package on the machine needs a login or a secret that is not there yet. The machine works; only the tool that needs the login does not. It is a warn, not a fail, so doctor still exits 0.

What to do: Run the command in the detail: devmachine login <credential> for a login, or devmachine secrets set <name> then devmachine credentials push for a secret.

update summary says doctor machine X unreachable, and update exited 0

What it means: doctor could not reach machine X (configuration, host key or connection failed), so update skipped its sync check; the sync line says X skipped (unreachable). That is about the machine, not about update, so it does not change update’s exit code.

What to do: Run devmachine doctor --machine X to see which check failed, fix it, then run devmachine update again or devmachine sync --machine X.

doctor says skip cli could not find the latest release

What it means: GitHub could not be asked: you are offline, or GitHub answered 403 because this address used up its 60 unauthenticated requests for the hour. It says nothing about your CLI, which is why it is a skip and not a failure.

What to do: Nothing, usually — the next doctor asks again. Once an answer arrives, it is kept for 6 hours.

update found changes and did not ask

What it means: There was no terminal to ask in — a cron job, a CI step, or input from a pipe — and --yes was not given. With nobody to answer, update applies nothing.

What to do: Run the devmachine sync command it printed, or pass --yes if this is automation you trust to change servers.

update says “—format json is not supported”

What it means: update asks a question and prints progress for a person. There is no single JSON document it could promise.

What to do: For a script, use devmachine doctor --format json and devmachine sync --check --format json.

packages outdated: “cannot tell the latest packages release, and none was read before”

GitHub could not be asked which packages release is the newest, and no earlier answer is stored in your cache folder. It is about the network (offline, a proxy, or GitHub’s limit of 60 unauthenticated requests an hour), not about your configuration. Try again when online. Once an answer is stored, the command works offline with that answer.

A line says “packages vN is out (you pin vM)”

A packages release newer than the one config.yml pins is out. Nothing is wrong: devmachine update moves the pin, and devmachine update --no-machines does it without touching a machine. The line shows at most once a day; DEVMACHINE_NO_UPDATE_HINT=1 turns it off. See Updating.

“source.run ”…” has spaces”

What it means: Without shell: true, run names one program, and args holds its arguments, each passed as it is. df -h / is read as a program called df -h /, which does not exist. Nothing ran.

What to do: Write run: df and args: [-h, /]. If you need a pipe or &&, set shell: true; then run is a shell line.

“source.run is a shell line, so it cannot hold {{…}}”

What it means: A value written into a shell line becomes part of the code the shell runs, so a value such as a; rm -rf ~ or $(id) would run as a command. No way of quoting it is safe in every case, so a shell line holds no templates at all.

What to do: Read the value from the environment variable the app sets, in double quotes: {{inputs.max_lines}} becomes "$DM_INPUT_MAX_LINES", {{context.workspace}} becomes "$DM_CONTEXT_WORKSPACE" (the workspace’s name). The name is upper case, and any character other than A–Z and 0–9 turns into _. Do not pass that variable on to eval, sh -c, ssh <host> …, awk or xargs: they run their argument as code. Bash arithmetic does too — $(( )), (( )), let, [[ … -gt … ]], declare -i run a value such as a[$(id)] — and /bin/sh on a Mac is bash. Check a number with case or [ … ] first: case $DM_INPUT_MAX_LINES in ''|*[!0-9]*) exit 1;; esac.

“a shell line takes no source.args”

What it means: With shell: true, run is the whole line, so there is no program for args to go to.

What to do: Write the words in run, and read values from $DM_INPUT_<NAME> or $DM_CONTEXT_<KEY>. Or drop shell: true and keep run as the program and args as its arguments.

“source.run cannot hold {{…}}: a value must not pick the program”

What it means: Without shell: true, run is the program that starts. If a value could fill it in, whoever sets the value would choose what runs.

What to do: Name the program in run and put the value in args: run: du, args: [-sh, --, "{{inputs.path}}"]. The -- stops a value that starts with - from being read as an option.

“source.run ”…” starts with -” or “has =”

What it means: Without shell: true, run names the program to start. A first word that starts with - reads as an option, and a word with = as a variable to set, so the program you meant would not run.

What to do: Put the program’s name in run and options in args. To set a variable for the program, set shell: true and write run: LC_ALL=C df -h /.

“source.script ”…” is not executable” or “only its owner can run it”

What it means: The file a package widget runs is copied to the machine with the same mode it has in the package. Without the execute bit nobody can run it; with chmod 700 only the machine’s admin can, and a workspace runs it as its own account.

What to do: chmod 755 <the file>, then run devmachine sync so the machine gets the new copy.

“a stream runs while the widget is on screen: remove source.every”

What it means: mode: stream keeps one command running and shows its lines as they come, so “how often” and “how long” do not apply. A stream also reads line by line, so number and json do not apply either.

What to do: Remove every and timeout, and use parse: text, lines or ansi. For a value checked every so often, leave out mode.

“view.kind ”…” takes …, and this … source gives …”

What it means: Each view draws some kinds of output. A gauge needs a number; a command parsed as text gives text. devmachine widgets schema lists what every view takes.

What to do: Set source.parse to what the view takes, or pick a view that takes what the source gives.

“view.value picks what to show out of the JSON”

What it means: The source parses its output as JSON, which can hold many values, and the view shows one. It needs to be told which.

What to do: Add value: "{{json.<field>}}" to the view, for example value: "{{json.disk.used}}" for {"disk": {"used": 41}}.

“view.ok … is not a rule”

What it means: A status rule is a comparison and a value: < 300, >= 99.5, == "up". Text can only be compared with == or !=.

What to do: Rewrite the rule in one of those shapes. Quote the whole rule in YAML when it holds a quote: ok: '== "up"'.

“view.ok … compares by size, and this … source gives text”

What it means: The status view’s source gives text (parse: text, or a command source with no parse), and a rule uses <, <=, > or >=. Text has no size to compare, so the rule could never hold.

What to do: Compare with == or !=, like ok: '== "up"'. If the output is a number, say so: parse: number on a command source, or leave parse out on a url source to compare its status code.

“requires engine >= 1.8, and this CLI implements engine 1.7”

What it means: The widget says it needs a newer engine than this CLI has. Nothing else in it was checked.

What to do: devmachine update.

“source.permission_mode X: a claude prompt takes …”

What it means: Each coding agent has its own names for what it may do, and permission_mode takes only those of the widget’s harness. A Codex name on a Claude prompt, or the other way round, is refused, and so is a template: the mode is what you approve, so it cannot change when the widget runs.

What to do: Pick a name from the list in the message, or take the key off to run the coding agent as it does by default. If your coding agent has a mode the list lacks, devmachine update: a CLI release adds new modes.

“permission_mode X runs without any check, so it runs only when you press refresh”

What it means: bypassPermissions (Claude), danger-full-access and dangerously-bypass-approvals-and-sandbox (Codex) let the coding agent change files and run commands without asking. Such a widget never runs on a timer, so its every must be manual. A board entry’s every and widgets set --every follow the same rule.

What to do: Write every: manual (or leave every out of a prompt source: manual is its default), and press the widget’s refresh button when you want an answer. To run it on a timer, pick a mode with checks.

“a widget with source.permission_mode needs requires.engine ”>= 1.6""

What it means: An app on engine 1.5 does not know permission_mode and would refuse the widget with no hint why.

What to do: Write requires: {engine: ">= 1.6"}. An app that is too old then says it needs an update.

“input X is a choice, and needs from”

What it means: A choice input is picked from a list, and from says which list: machines, workspaces or harnesses (the coding agents). Without it, or with another name, the app has nothing to offer.

What to do: Add from: machines (or one of the other two). Add many: true when the person may pick more than one.

“input X takes its options from Y, which is not a source”

What it means: from names the list a choice is picked from, and there are three: machines, workspaces and harnesses. Any other name gives the app nothing to offer.

What to do: Write one of the three, for example from: machines.

“input X: many is …: write true or false”

What it means: many says whether the person may pick more than one name. It is a yes or no, so a word such as maybe is refused.

What to do: Write many: true, or many: false (the same as leaving it out).

“input X is a list of choices, and its default … is not”

What it means: The input has many: true, so its value is a list, and so is its default, even for one name. The other way round, “is one choice, and its default [main] is not a name” means a list was written where the input takes one name.

What to do: Write default: [main], or default: [] for all; for an input without many, write default: main.

“input X is a string: from and many belong to a choice”

What it means: from and many only mean something on a choice input. On a string, number or boolean they are a mistake, often a type: left over from before the input became a choice.

What to do: Write type: choice, or remove from and many.

“a widget with a choice input needs requires.engine ”>= 1.5""

What it means: An app on engine 1.4 or older has no chooser, so it could not show the input at all. The widget’s requires.engine still lets such an app read it.

What to do: Write requires: {engine: ">= 1.5"}. An older CLI then says “update” instead of hiding the widget for a reason nobody can read.

“input X takes a list of names, written [a, b]”

What it means: The widget’s input is a choice of many, so a board’s with holds a list for it, even for one name. The same goes the other way: “takes one name” means the board holds a list where the widget takes a single name.

What to do: Write with: {machines: [main]}, or set it with devmachine widgets set <id> --board <area> --set machines=main, which writes the right shape.

“warning: … names machine “X”, which config.yml does not have”

What it means: A widget on the board picked a machine (or workspace) that is not in config.yml any more, or a coding agent the engine does not know. The app leaves that name out and draws the rest. Nothing is refused.

What to do: Pick again in the app (⋯ → Choose), or run devmachine widgets set <id> --board <area> --set machines=<names>.

“every 1s is below X’s minimum of 5s”

What it means: A board entry’s every asks the widget to run more often than its source allows. The minimum comes from the source: an app provider, a package provider’s min_every, or the source kind (5m for a prompt). The message names the widget and its minimum.

What to do: Write the minimum or more, or take the key off to use the widget’s own. On a provider widget, manual is refused too: it runs on a schedule.

“a widget written in the board sets how often in source.every, not every”

What it means: The entry has its own source, so how often it runs is source.every. An every next to it would say the same thing twice.

What to do: Change source.every and delete the other line. The app asks for your approval again when the source changes.

“X is written in the board: change its source in the board file”

What it means: widgets set --every or --set was given for a widget that has its own source in the board. Those change what it runs, which the app asks you to approve, so the CLI does not change them from flags. A widget written in the board has no inputs either.

What to do: Edit source in the board file and run devmachine widgets validate on it, or use ⋯ → Edit… in the app. --title alone still works.

“nothing to change: give —title, —every or —set”

What it means: widgets set was run with only an id and a board.

What to do: Say what to change, for example devmachine widgets set usage --board home --every 2m.

“source.target: app/… is the app’s own data, so it takes no target”

What it means: The widget reads one of the app’s own providers, such as app/clock. The app has that data itself, so there is nothing to run on a machine and no time limit to set.

What to do: Remove source.target and source.timeout. To read data from a machine, use a package provider (<package>/<command>) or a command source.

“a package with widgets needs requires.cli above 0.8.1”

What it means: The package has widgets:, but its requires.cli lets a CLI older than 0.9.0 use it. That CLI ignores widgets: without a word, so the widgets would never be checked or listed.

What to do: Add requires: {cli: ">= 0.9.0"} to package.yml.

widgets list fails with “finding the latest packages release”

What it means: Nothing is pinned in config.yml, or there is no config.yml yet, so the CLI asked GitHub for the latest packages release to read widgets from, and could not reach it. The app shows this as “could not fetch packages”.

What to do: Check the network and run it again. Once a release is pinned — setup pins one, and so does devmachine packages pin — and in the cache, widgets list works offline.

widgets validate says ”… is neither a widget, a package nor a board”

What it means: The path exists, but validate cannot tell what to check. It knows a path by what it holds: a file named widget.yml, a folder with a widget.yml, a folder with a package.yml, or any other file, which it reads as a board. This is a folder with none of those in it, such as a package’s widgets/ folder or <config>/boards/ itself. Nothing was checked.

What to do: Pass the package folder (the one with package.yml), one widget folder, or one board file. To check every board and every widget of your own packages, run devmachine widgets validate with no path.

“X does not fit the home area” (or another area)

What it means: The widget’s fits does not include the area’s layout (canvas for Home, stack for both sidebars, slot for the menu bar, tabs for its popover), or it requires a context key the area does not give. widgets add says it before writing; widgets validate says it for a board you wrote by hand. devmachine widgets help <name> lists the areas it fits. In the menu bar the view must also draw one line: “does not fit the menubar area: the X view cannot be drawn in the menu bar”.

What to do: Pick a widget that fits the area, or, for your own widget, add the layout to fits. A widget that needs session fits only the Context tab.

“X needs context.session, which the sidebar area does not give”

What it means: The widget reads the selected session, and only the Context tab has one. The same goes for a widget written in a board whose provider needs it (“which this board’s area does not give”).

What to do: Put it on the Context tab instead.

“X goes on a board once”

What it means: The widget says single: true: the app’s workspace list is one, since two copies would fight over the same selection and order. On a missing sidebar.yml the CLI reads the default board, which already holds the workspace list.

What to do: Keep one. To move it, use devmachine widgets move; to bring it back after removing it, devmachine widgets add devmachine-app/workspaces --board sidebar.

“—at places a widget on Home’s canvas” or “—after and —before order a sidebar’s list”

What it means: Home is a canvas: a widget there has a position, given with --at. The sidebars, the menu bar and its popover are lists: a widget there has a turn, given with --after or --before. Each flag only means something in its own kind of area.

What to do: On Home use --at x,y or nothing; in a sidebar, the menu bar or its popover use --after <id>, --before <id> or nothing (the end of the list).

“the home area is a canvas: a widget there has a place, not a turn in a list”

What it means: widgets move orders a sidebar. Home has no order: each widget has its own position, and they may overlap.

What to do: Drag it in the app, or change its frame in home.yml. To move a widget in a sidebar, pass --board sidebar or --board context-sidebar.

“X cannot move next to itself”

What it means: --after or --before named the widget being moved.

What to do: Name the widget it should sit next to.

“—after needs an id” or “—before needs an id”

What it means: The flag was given with an empty value, often from an unset shell variable (--after "$ID"). The CLI does not read that as “not given”: it would put the widget at the end without a word.

What to do: Give the id, or leave the flag out.

“no widget with id “X” on the sidebar board”

What it means: --after, --before, move or remove named an id the board does not have. On a missing sidebar board the ids are those of the default board (workspaces; shortcuts, todo and the others).

What to do: Check the ids in the board file, or with devmachine widgets validate, and run the command again.

“port: the X view is drawn only in stack, and this board’s area is laid out as canvas”

What it means: A widget written in a board uses one of the app’s sidebar views, such as app.publish-port, and those are drawn only in a list. Home is a canvas.

What to do: Move the widget to a sidebar board, or pick a view that is drawn anywhere, such as list or text.

“source.name app/session-context needs context.session”

What it means: The provider reads the session that is selected in the app, so it only works in the Context tab, which hands every widget there that session. A widget only sees the context keys it declares.

What to do: Add context: {session: required} to the widget.yml. The widget then fits only the Context tab, which is right: there is no session to read anywhere else.

“fits canvas, and the X view is drawn only in stack”

What it means: The view is one of the app’s sidebar views (app.workspaces, app.todo and the others). They are lists, drawn as tall as their content, so they have no shape on Home’s canvas.

What to do: Write fits: [stack].

“places “X”: the widget does not fit that area”

What it means: places asks the app to add the widget to an area once. The widget cannot sit there: its fits lacks the area’s layout, or it requires a context key the area does not give (session, for example, only the Context tab gives). The app would skip it without a word.

What to do: Remove the area from places, or change fits or context so the widget fits it. devmachine widgets validate lists the areas it fits.

“X is not available yet: add the package”

What it means: The widget reads something its package installs, and that package is not on any machine or workspace in config.yml — or it is, and no sync has applied it yet (packages.lock does not list it).

What to do: Run the command the message names: devmachine packages add <package> --machine <name>, then devmachine sync.

“the board has a problem, so it was not changed”

What it means: widgets add or widgets remove read the board and found a mistake, listed under the message with its line. The CLI never rewrites a broken board: it would replace your text with its guess and could drop widgets.

What to do: Fix the lines it names, check with devmachine widgets validate, and run the command again. The app keeps the last good layout meanwhile.

“the board changed on disk since it was read; run the command again”

What it means: Something else — usually the app, after you moved a widget — wrote the board between the moment the CLI read it and the moment it was about to write. Writing anyway would have lost that change.

What to do: Run the same command again.

“there is no home board at …”

What it means: widgets remove found no Home board file, so there is nothing to take off. Nobody has placed a widget there from the CLI, or the app has not saved a layout yet. widgets add creates the file; remove never does on Home. A missing sidebar board is different: it is read as the default board, so remove and move work on it.

What to do: Check --board and the configuration folder the path names. To see what is on a board, open <config>/boards/<board>.yml.

“a widget written in the board needs a title”

What it means: A board entry with a source or a view and no type is a widget written in place. It needs a title (what the card shows), a source and a view. An entry with a type and a source mixes the two kinds and is refused too.

What to do: Add the missing key, or, for a widget from the gallery, keep only type and with.

“a widget written in a board names an absolute path on the target”

What it means: A widget in a board belongs to no package, so a relative script has nothing to be relative to.

What to do: Write the full path on the target, for example /home/alice/bin/check-disk, or use run with args.

“a widget in a sidebar has no frame; its place is its position in the list”

What it means: A sidebar board is a list: the first widget is drawn at the top, the next under it. frame and z place a widget on Home’s canvas and mean nothing here. The same message says z for a z key.

What to do: Delete the frame (or z) line. To change the order, move the entry in the file, drag its header in the app, or run devmachine widgets move <id> --before <other> --board <area>.

“a widget in a sidebar folds with collapsed: true, not minimized”

What it means: Home folds a widget into a pill (minimized); a sidebar folds it to its header (collapsed). Each area takes only its own key. The opposite message, “a widget on a canvas folds with minimized: true, not collapsed”, is the same mistake on Home.

What to do: Rename the key.

The same message comes for minimized: false: a stack refuses the minimized key whatever its value. Delete the line.

“size auto follows the content, and the X view does not grow”

What it means: auto makes a widget as tall as what it shows. Only a view that has a natural height works that way: the app’s sidebar views (app.workspaces, app.todo and the others), the summary, machines and coding agent usage views, and the generic text, number, status, list and markdown. Every other view (a clock, a gauge, a web page, a terminal) has a fixed shape and needs a preset. The same message comes on Home, from a board entry or from widgets add --size auto (“<widget> does not grow with its content, so it takes no —size auto”).

What to do: Use one of the sizes the message lists, or leave size out to get the widget’s default_size.

“frame needs h unless size is auto”

What it means: A widget on Home has a frame with x, y and w but no h, and its size is a preset or custom. Only size: auto leaves the height out, because the app takes it from the content. Everywhere else the height is part of the box.

What to do: Add h to the frame, or write size: auto if the view grows with its content.

“frame width … is narrower than …”

What it means: On Home, a view that grows has no least height, but its width still has a floor: the width of the smallest preset it takes. Below that the content has no room to draw.

What to do: Make w at least the number in the message. A view that does not grow has a floor on both sides and gets “frame WxH is smaller than …” instead.

“size “X” in a sidebar is auto or one of …”

What it means: A sidebar widget takes auto or a preset it lists in sizes. custom exists only on Home, after a free resize.

What to do: Pick a size from the list in the message.

“the menubar holds 3 widgets”

What it means: menubar.yml has more than three entries, or widgets add would make it four. The menu bar title shares a thin strip with the clock and every other app’s items, so it holds three short widgets. widgets add adds “take one off first with devmachine widgets remove <id> --board menubar”; on a missing menubar.yml it counts the two default widgets.

What to do: Take one off with devmachine widgets remove <id> --board menubar, or put the widget in the popover instead (--board menubar-panel) if it fits there.

“a widget in the menu bar has no size: it is one line of text, so it takes no —size” or “a tab fills the menu bar popover, so it takes no —size”

What it means: widgets add --size sets how big a widget is on Home or in a sidebar. A menu bar widget is one line and a tab fills the popover, so neither has a size.

What to do: Leave --size out.

“a widget in the menu bar has no size: it is one line of text”

What it means: A menu bar widget is one line, so it has no size. It has no frame or z either (its place is its turn in the list), and it does not fold (collapsed, minimized). The message names the key it found.

What to do: Delete that line. To change the order, move the entry in the file or run devmachine widgets move <id> --before <other> --board menubar; to hide a widget, remove it.

“the X view cannot be drawn in the menu bar”

What it means: The menu bar title draws text and at most one symbol, so only the text, number, status and app.brand views work there. A widget written for engine 1.0 may list slot in its fits with another view, such as app.clock; it is still a good widget, it just does not fit the menu bar. A widget with no view.kind at all gets “a widget with no view cannot be drawn in the menu bar” instead.

What to do: Put it on Home, a sidebar or the popover (devmachine widgets help <name> lists where it fits), or write a widget with one of those four views.

“a tab in the menu bar popover has no frame; its place is its position in the list”

What it means: Each widget in menubar-panel.yml is a tab, in the order written. frame and z place a widget on Home and mean nothing here; a tab does not fold either, so collapsed and minimized are refused with “does not fold”.

What to do: Delete the line. Reorder with devmachine widgets move <id> --before <other> --board menubar-panel.

“warning: … size is ignored in the menu bar popover: a tab fills it”

What it means: A tab always fills the popover, so its size does nothing. It is only a warning: the board is valid, and the CLI keeps the line when it rewrites the file.

What to do: Delete the size line if you want the warning gone.

“source.target names machine ”…”, which config.yml does not have”

What it means: A widget written in a board runs on a machine or a workspace your configuration does not have — removed, renamed, or a typo. The app shows the widget’s error instead of data. For a package widget this is only a warning: its author’s names are not yours.

What to do: Point target at a name devmachine machines list or devmachine workspaces list shows, or remove the widget. widgets add and remove still work on the board in the meantime.

“provider X is not one of commands”

What it means: package.yml lists X under providers, but not in commands. devmachine run --package refuses a command that is not in commands, so a widget reading X would never get an answer.

What to do: Add X to commands, or remove it from providers.

“provider “X”: use lower case letters, digits, dashes and underscores, starting with a letter”

What it means: A key under providers in package.yml is not a name a widget can use. A widget names a provider as <package>/<command>, and the app runs it as devmachine run --package <package> <command>, so the key must be a plain command word: no capital, space, dot, slash or leading dash.

What to do: Rename the provider and the matching entry in commands, for example disk-usage instead of Disk Usage.

“providers are commands of an entrypoint, and this package declares none”

What it means: package.yml has a providers key but no entrypoint. A provider is one command of the package’s entrypoint: the app runs the entrypoint with that command and reads the JSON it prints. Without one there is nothing to run.

What to do: Add entrypoint: bin/<name> pointing at an executable in the package, with each provider listed in commands. devmachine packages new writes one. If the package has no command to offer, remove providers.

package.yml says “did not find expected ’,’ or ’}’”

What it means: A line written between { and } holds a value YAML cannot read there. The usual one is an optional type in returns: {note: string?}. Inside braces, ? needs quotes.

What to do: Write {note: "string?"}, or put each field on its own line under returns:, where no quotes are needed.

“provider X min_every … is below the 5s floor”

What it means: A widget may run a package’s command at most every 5 seconds; a provider cannot promise more, because each run is a connection to a machine.

What to do: Write min_every: 5s or more. Pick what the command can really afford: one that reads every container on a machine wants 30s.

“a package widget reads only its own package’s providers”

What it means: A widget in package A names B/<command>. The app shows a widget only when its package is on the machine, so a widget that read another package’s command could look ready while that package is missing.

What to do: Ship the widget in package B, or write it straight into a board: a widget written in a board may read any package’s provider.

“X has no provider C” or “no package X”

What it means: The widget names X/C, and package X does not list C under providers in its package.yml — or there is no package X in the pinned release or your own packages. A board widget is checked by devmachine widgets validate; widgets add and remove keep working, so removing a package never locks a board.

What to do: Check the name against devmachine widgets list --format json (its providers lists every one), or add C to the package’s providers.

“a package provider runs on a machine or workspace”

What it means: A package’s command lives on the machine its package was synced to. There is nothing to run on your own computer.

What to do: Add target: {machine: <name>} or target: {workspace: <name>}. To run something on your computer, use a command source.

“source.with.X: … gets it as —X”

What it means: Each key of with becomes a flag, --X, before its value. A key with capitals, spaces or a leading dash would turn into a different flag than the one you wrote.

What to do: Write the key in lower case letters, digits, dashes and underscores, starting with a letter. The value can be any text.

“a widget reading a package provider needs requires.engine ”>= 1.3""

What it means: The app’s engine 1.2 does not know package providers, and its requires.engine lets that app try.

What to do: Write requires: {engine: ">= 1.3"}.

“source.name X: is written /, …”

What it means: A provider name with a slash that does not start with app/ names a package’s command. The CLI and the app turn that name into a package folder and a command to run on a machine, so it must look like one: a package name and a command name, each in lower case letters, digits, dashes and underscores, starting with a letter. A template, a space, a capital or a leading dash is refused. Unlike “no package X”, widgets add, move and remove refuse this too, because a board that holds such a name is unsafe to hand to the app.

What to do: Fix the name in the board, for example devmachine-app/stats. devmachine widgets list --format json lists every provider under providers.

Installing from a git@ address fails with “Host key verification failed” or “Permission denied (publickey)”

What it means: A git@host:path address goes through ssh, and ssh would normally ask its own questions: whether to trust a host it has never seen, or the passphrase of your key. The CLI runs it with BatchMode=yes, so it never asks — nobody may be at a terminal to answer, the macOS app included — and fails at once instead. It also ignores a GIT_SSH_COMMAND set in your shell for the same reason; ~/.ssh/config still applies.

What to do: Run ssh -T git@<host> once to trust the host, and load your key into the SSH agent with ssh-add. Then install again. An https:// address of a public repository never needs either.

”… its widgets are treated as third-party”

What it means: A package in <config>/packages/ has a .devmachine-source.yml, the file packages install writes, and it does not read. The CLI cannot tell where the package came from, so it treats it as the least trusted kind: its widgets that run code ask first.

What to do: Run devmachine packages update <name> to fetch it again and rewrite the file. If you wrote the package yourself, delete the file.

“X is an official package: a package from a git address cannot take its name”

What it means: The pinned packages release already has a package called X. A package in your own folder always wins over the release’s of the same name, so installing this one would quietly replace the official X on every machine that has it.

What to do: Ask the package’s author to rename it. If you wrote it, rename it: name in package.yml.

“you already have your own package X”

What it means: <config>/packages/X/ exists and you wrote it — it has no .devmachine-source.yml. install never writes over your own work.

What to do: Rename one of the two, or move yours away first.

“X is already installed from …”

What it means: You installed X from a git address before. When the message says only “from a git address”, its .devmachine-source.yml does not read, but it is there, so the folder is still not yours to overwrite.

What to do: devmachine packages update X fetches it again.

”… has no package.yml at its top”

What it means: The repository is not one package: package.yml is not in its top folder. A repository holding several packages, or a package in a subfolder, cannot be installed.

What to do: Ask the author to publish the package in its own repository, or copy its folder into <config>/packages/ yourself.

What it means: The repository holds a symbolic link to a file outside the package. sync would copy whatever it points at — a key on your computer, for instance — to every machine the package is added to.

What to do: Do not install it. Tell its author: a package holds its own files.

“the package at … has a character that moves or hides text in a terminal in …”

What it means: A file name in the repository, or the package’s summary, a command, a provider, a credential or a package it needs, holds a control character (ESC, a carriage return, DEL and the like) or a Unicode bidirectional mark or override, or a file name is not UTF-8. Printed as it is, such a name can move the cursor and erase the lines above it — the list of tasks, or the warning that they run as root — so the prompt would show less than the package brings. The message prints the name with the character written as an escape, such as \x1b or \u202e. Nothing was written.

What to do: Do not install it. Tell its author which name it is: a package names its files and what it brings in plain text. A repository that does this on purpose is not one to trust with root.

“fetching …: …”

What it means: git could not fetch that address or ref. Its own message follows: a repository that does not exist, a ref that is not there, no access to a private repository (git does not ask for a password here, and ssh does not ask anything), or no network.

What to do: Check the address and the ref in a browser or with git ls-remote <address>. For a private repository, use a git@ address with an SSH key that has access, loaded in your SSH agent.

“git is not installed”

What it means: packages install and update fetch with git, and it is not on your PATH.

What to do: Install git (on a Mac, xcode-select --install).

“the package at … has N problem(s)”

What it means: The fetched package does not pass packages validate. Every problem is listed with its file and line. Nothing was written.

What to do: Tell the package’s author; each line says what to fix.

”… appeared while X was being fetched: nothing was written”

What it means: packages install checked that <config>/packages/X/ did not exist, fetched the package, and found the folder there when it went to move it in: another command or you made it in the meantime. Install never writes over a folder, so it stopped.

What to do: Look at what is in <config>/packages/X/. If it is a copy you do not want, delete it and install again.

“checking whether X is an official package: …”

What it means: Before installing, the CLI reads the pinned packages release to make sure X is not one of its names, and that read failed for a reason other than “no package named X” — a damaged download in <config>/cache/, for instance. Not knowing, it refuses rather than risk replacing an official package.

What to do: Fix what the rest of the message names. For a damaged cache, delete <config>/cache/packages/<release>/ and run the command again; it downloads the release afresh.

”… putting the old copy back failed: …; it is in …”

What it means: An update moved the old copy of a package aside, could not move the new one in, and then could not move the old one back. Both moves are renames inside the same folder, so this means the disk or its permissions changed under the command. The old copy is not deleted: it stays at the path the message names, and the next fetch never sweeps it.

What to do: Fix the disk or the permissions, then move that folder back to <config>/packages/X/ yourself.

“X is your own package, not one installed from a git address”

What it means: packages update and packages remove work only on a package installed with packages install, which leaves a .devmachine-source.yml in its folder. X has none: you wrote it, and the CLI never fetches over it or deletes it.

What to do: Edit your package in <config>/packages/X/. To delete it, delete the folder yourself.

“X is still on machine …: take it off first”

What it means: config.yml still lists X on that machine or workspace. Deleting the package would make the next sync fail to find it.

What to do: devmachine packages rm X --machine <name> (or --workspace <name>), devmachine sync, then devmachine packages remove X.

“X is in the future workspace defaults”

What it means: defaults.workspace in config.yml lists X, so every workspace you create from now on starts with it. Deleting the package would make creating the next workspace fail to find it.

What to do: devmachine workspaces defaults --rm X, then devmachine packages remove X.

“the fetched copy of X was swept away while waiting for your answer”

What it means: packages install or update fetches into <config>/packages/.install-…/ and then asks. A fetch folder older than an hour is taken as one a Ctrl-C left behind, and the next install or update deletes it. The question stayed open long enough for that to happen, so there is nothing left to install.

What to do: Run the command again and answer the question.

A package is gone after a Ctrl-C during packages update

What it means: update swaps the new copy in with two renames: the old folder moves to <config>/packages/.install-…/.previous, then the new one moves into its place. A Ctrl-C between the two leaves neither in <config>/packages/X/. Nothing is lost: both copies are inside that .install-… folder, and the hourly sweep never deletes a folder that holds a .previous.

What to do: Find the folder with ls -a <config>/packages/. To keep the version you had, move .install-…/.previous back to <config>/packages/X. To take the new one, move .install-…/X there instead; it was already checked and records its new commit. Then delete the .install-… folder.

“X is installed from …, and packages release vN has an official X”

What it means: sync found a package installed from a git address whose name the pinned release now has too: a packages pin brought a release that added it after you installed yours. A package in your own folder always wins over the release’s, so your copy would replace the official one on the machine without a word. sync stops before it connects instead of picking one, since the two share a name, not an author.

What to do: To use the official one, take the third-party one off with devmachine packages rm X --machine <name> (or --workspace <name>), delete it with devmachine packages remove X, then add the official one back and sync. To keep the third-party one for now, pin the release you had before with devmachine packages pin <release>.

”… now holds a package named Y, not X”

What it means: The repository X was installed from now holds a package with another name. Updating would leave the configuration naming X while the folder holds Y.

What to do: devmachine packages remove X, then devmachine packages install <address>, and change X to Y wherever config.yml names it.

“the address recorded in …/.devmachine-source.yml: …”

What it means: packages update checks the address it finds in the package’s .devmachine-source.yml the same way packages install checks the one you type, and that address is not an https:// or git@ one. Somebody edited the file by hand, so nothing was fetched.

What to do: Put back the address the package came from, or devmachine packages remove X and install it again.

”… is required”, ”… is not a field of this list” or “a number, got the string …”

What it means: A setting does not fit the type its package declares for it, for example workspace.repos[0]: "url" is required. The text before the colon is the setting, and [0] is its first entry. The command that wrote it refused it, or sync stopped before reaching the machine, so nothing on the machine changed.

What to do: Fix the value with --set, or in config.yml if the setting was written by hand. devmachine --format json packages list shows each variable’s type, and the settings reference names the fields a list’s entries take. A field the list does not take is usually a typo of one it does: the message lists the ones it accepts.

“No attention dot when the agent waits”

What it means: The attention dot comes from the terminal bell, and the agent never rang it. tmux marks a window only when a bell reaches it, so a waiting agent that stays silent leaves no mark.

What to do: Make the agent ring the bell when it waits. For Claude Code, set "preferredNotifChannel": "terminal_bell" in ~/.claude.json on the machine, or run claude config set --global preferredNotifChannel terminal_bell as the workspace user. See session indicators.

“The spinner stops while the agent is still thinking”

What it means: Busy means the screen changed in the last 5 seconds. An agent that thinks without drawing anything looks idle until it prints again. The agent is still working.

What to do: Nothing is broken. Wait for the next change on the screen, or open the session to see what the agent does. See session indicators.

“scheduled is not set up on …”

What it means: The workspace has no scheduled package, or it is in your configuration but the machine has not been synced since. The timer that runs tasks and the devmachine it calls are not there yet.

What to do: Add the task again with --yes, which sets up the package and syncs the machine first. Or do it by hand: devmachine packages add scheduled --workspace <w> --yes, then devmachine sync --machine <m> --tags scheduled --yes. See scheduled tasks.

“scheduled’s setup on … did not finish”

What it means: The scheduled package is in the workspace’s configuration, but the devmachine it installs is not at ~/.devmachine/scheduled/devmachine. The sync that set it up failed or was stopped. The error kind is setup-incomplete, and the app offers “Finish setup”.

What to do: devmachine sync --machine <m> --tags scheduled. Or add the task again: scheduled add runs that sync first, after asking, or at once with --yes. If the sync fails again, the error names the task that failed. See a setup that did not finish.

“setting up scheduled on … failed”

What it means: The sync that sets up the scheduled package failed. The error names the first Ansible task that failed and what it said, such as "scheduled : Unpack the release": Failed to find handler. The package stays on the workspace, so fixing the cause and syncing again finishes it.

What to do: Fix what the task says, then run devmachine sync --machine <m> --tags scheduled.

A Mac: “Unpack the release” fails with “GNU tar required”

What it means: Packages releases before the fix unpacked the devmachine release with Ansible’s unarchive, which needs GNU tar. macOS ships bsdtar, so unarchive falls back to unzip, which cannot read a .tar.gz: Command "/usr/bin/tar" detected as tar type bsd. GNU tar required. and Command "/usr/bin/unzip" could not handle archive. Linux has GNU tar, so it only fails on a Mac. The session-share package had the same step.

What to do: devmachine update to a packages release with the fix, then devmachine sync --machine <m> --tags scheduled. Installing GNU tar is not needed.

“the scheduled package is not in packages release …”

What it means: Your configuration syncs from a packages release that came out before the scheduled package. Adding it anyway would leave the workspace with a package every later sync refuses, so nothing was changed.

What to do: devmachine update once a packages release with scheduled is out, then create the task again.

“the devmachine on … is older than this one”

What it means: The workspace runs an older devmachine than your computer, and it answers in a shape this one does not read. It happens after you update the CLI on your computer and before the machine is synced.

What to do: devmachine sync --machine <m> --tags scheduled. The package installs the devmachine of the release your configuration pins.

A scheduled run ends with “claude is not installed for this account”

What it means: The task’s agent is not on the workspace’s PATH. A scheduled prompt runs as the workspace’s own account, so that account needs the agent, and its login.

What to do: Add the agent’s package to the workspace, claude-code or codex, sync, and log in once in a session there. Then press Run now, or devmachine scheduled run <id> --workspace <w>, to try again.

A scheduled run is missed

What it means: The machine was off or asleep when the task was due. A run found more than two minutes late is recorded, not started. Nothing is wrong with the task.

What to do: Nothing, or devmachine scheduled run to run it now. A task on a laptop that sleeps runs only while it is awake.

A scheduled run is skipped

What it means: The task’s previous run was still going when the next time came. Two runs of one task never go at once.

What to do: Give the task a longer gap, or a shorter --timeout so a stuck run ends sooner.

A scheduled run fails with “folder … does not exist”

What it means: The task’s folder is not in the workspace any more, or was never there. ~ is the workspace’s home, not your computer’s.

What to do: devmachine scheduled edit <id> --workspace <w> --folder <f>.

A scheduled prompt ran, succeeded, and did nothing

What it means: The agent needed approval for a tool, and nobody was there to give it. With a mode that asks first, such as Claude’s manual, the agent stops at the first tool it needs.

What to do: Read what it said with devmachine scheduled log. Then pick a mode that lets it work. acceptEdits approves file edits only, so a prompt that uses a connector (Linear, email) is refused with “permission … denied”; use auto: devmachine scheduled edit <id> --workspace <w> --permission-mode auto.

“A session vanishes from the app about 30 seconds after you open it”

What it means: devmachine sessions read the workspace as having no sessions, while tmux still runs them. Up to CLI v0.13.0 this happened on a machine whose ssh login sets no UTF-8 locale, which is every Mac: tmux then prints each tab in its list as _, and no line could be read. The app keeps a new session on screen for 30 seconds, then trusts the empty list and closes the pane. The session and what runs in it are untouched on the machine.

What to do: Update the CLI to the first release after v0.13.0. To check a machine by hand, compare LC_ALL=C tmux list-sessions -F '#{session_name}<Tab>#{session_windows}' with the same command under tmux -u; the first shows _ where the second shows a tab. See session indicators.

Chat error kinds

devmachine chat send and chat ask end a failed answer with {"type":"error","kind":"…","message":"…"}. What each kind really means:

  • unreachable — the workspace’s machine did not answer, or the connection dropped mid-answer. Same as in devmachine sessions: see “no address answered”.
  • login-refused — the machine answered but refused the workspace’s login. Most often the workspace is not synced yet. See “answered on … but refused the login”.
  • host-key-rejected — the machine’s key is not the one pinned. See it used to connect, and now it does not.
  • harness-missing — claude or codex is not installed for that account, or not on its login shell’s PATH. Add the claude-code or codex package to the workspace and run devmachine sync.
  • harness-logged-out — the harness is installed but not logged in for that account. Open a session on the workspace, run claude (or codex login) once and log in; the next message works.
  • harness-failed — the harness ran and reported an error. The message is the harness’s own, passed through: an overloaded API, a usage limit, a session id it no longer has. Retrying later often works; for a lost session, start a new chat.
  • cancelled — the answer was stopped (Esc in the app, Ctrl-C, or SIGTERM). What arrived before the stop is kept.
  • session-not-found — chat ask found no tmux session by that name on the workspace, or the --folder given does not exist. The session may have ended.
  • transcript-not-found — the session exists but its harness wrote no transcript for that folder yet: nothing was asked in it so far, or it runs in a folder other than the pane’s.
  • harness-unsupported — the session runs a harness Ask cannot answer about yet. Ask works on claude and codex sessions.

The app shows no scroll bar, even with “Show scroll bars: Always”

The macOS app always uses the thin scroll bar that shows only while you scroll, whatever System Settings → Appearance → “Show scroll bars” says. Its sidebars and panels are narrow, and the “Always” bar’s track would take their width. Scroll with the trackpad, the mouse wheel or the keyboard; the bar appears while the list moves.

A chat does not use a tool from my MCP server

What it means: chats start without the account’s MCP servers, hooks and plugins, because they are most of the harness’s start-up time. The harness cannot see the tool at all.

What to do: send with --mcp (devmachine chat send --chat <id> --mcp -- …). The chat keeps the choice for its later messages. For codex, --mcp also brings back the model and settings of ~/.codex/config.toml. See MCP servers are off unless you ask.

A chat session ends with "type":"closed","reason":"idle"

What it means: nobody sent a message for 10 minutes, so the session stopped its harness instead of keeping it running for nothing. The chat and its local copy are kept.

What to do: start another session with devmachine chat session --chat <id>; it resumes the same conversation.

A chat session ends with "reason":"error" before ready

What it means: the harness could not start. The error line before it says why, with the same kinds as chat send: harness-missing, harness-logged-out, unreachable and the others under chat error kinds.

What to do: fix what the kind says and start the session again.