Troubleshooting.

osewa's errors try to say what to do next. Here is each common one, what it means and the fix.

Connecting

can't be reached from here … open TCP port 7322

login set up the server, but your machine can't reach its port. Open TCP (and UDP) 7322 in the host's firewall or cloud security group. If the host is reached at a different address than ssh uses, for example through a tailnet, log in again with --addr. Nothing was saved, so just run login again once it's fixed.

unknown host "devbox"; run osewa login first

No host by that name in your hosts.json. Names are what you passed to --name, or the ssh target without user@.

context deadline exceeded

Nothing answered within 15 seconds. Check the server is running on the host (systemctl --user status osewa, or look for it in ps) and that the port is open from where you are now: a network that worked at login may block it.

It works, but connecting feels slow

Likely UDP is blocked, so QUIC loses the race and every connection waits 300 ms before the WebSocket starts. That's not an error, just slower. Force each carrier to see which one gets through:

OSEWA_CARRIER=ws osewa ls devbox     # TCP only
OSEWA_CARRIER=quic osewa ls devbox   # UDP only

If only ws works, open UDP 7322 too.

Keys and devices

auth: device not enrolled

The host doesn't list this device's key: it was revoked, or the host's devices file was reset, or this machine's client.key changed. Log in again to enroll.

auth: server key does not match pin

The host's key isn't the one saved at login. If the host was reinstalled or its ~/.config/osewa was wiped, log in again. If not, treat it as a warning: something may be impersonating the host.

has mode -rw-r--r--; it must be private (chmod 600)

A key or hosts.json is readable by others, so osewa won't use it. Run the chmod the message names. For directories, it's chmod 700.

Versions

incompatible protocol / incompatible snapshots … update osewa on the host or here

Your machine and the host run builds that can't talk to each other: a different wire protocol, or a different snapshot version. If your build is the newer one and the server still accepts it, osewa update devbox fixes it; otherwise log in again over ssh, which copies your build. osewa version --json on each side shows what differs.

host speaks protocol X, want Y

The same problem, found at login when --no-install kept the host's own osewa. Drop --no-install to send yours.

session … can't be attached: its holder is build …, the server …

The session was started by an older build, before an update that changed the protocol or the snapshot version. It's still running, but this server can't show its screen. osewa ls marks it incompatible. Finish or save what runs in it, then osewa kill devbox <id> and start a new one. A plain osewa attach devbox skips such sessions.

no osewa build for linux/amd64

The host is a different platform from your machine, and login or update has no build for it. A released osewa downloads its own release's build for the host, so this happens with a build from source, or when the download failed (the message says why). Put an osewa-linux-amd64 (or the platform named) next to your osewa, or in a directory named by $OSEWA_DIST.

The server

osewa server: already running (pid N)

Each user runs one server. This one is already up; you don't need another. To restart with new flags, use osewa service install with the flags.

listen tcp :7322: bind: address already in use

Something else holds the port, often another user's osewa on the same host. Pick another port for one of them (Changing the port).

The server is gone after a reboot

It was started with --daemon, which doesn't survive reboots. Log in again with --service, or run osewa service install on the host. On Linux, also run loginctl enable-linger $USER so it keeps running when you're logged out.

Still stuck

Look at the server's log (where it is), and open an issue with the error and both sides' osewa version.