Clavda troubleshooting: device offline and common install errors

Why a Clavda device stays offline and how to fix it: read the agent's log, and solutions for Exec format error, WEB_CLIENT_ID is required, sudo and ESP32 problems.

Start with the two checks below. They answer most problems in a minute. If they do not, find the message you are seeing under Common errors.

Check whether the device is connected

Open Devices in Clavda. A device turns green within a few seconds of connecting. The indicator comes from the live connection to the relay, not from a database record, so green means the device is connected right now, and grey means it is not.

Read the agent's log

The agent says why it cannot connect. On Linux, read it from the journal:

# system-wide install
sudo systemctl status clavda.service
sudo journalctl -u clavda.service -f

# non-root install
systemctl --user status clavda.service
journalctl --user -u clavda.service -f

On Windows and macOS, run the agent from PowerShell or Terminal to see the same output. An ESP32 logs to its USB serial port: see ESP32 does not connect.

For more detail, add LOG_LEVEL=debug to the agent's .env and restart it.

Common errors

`WEB_CLIENT_ID is required`

The agent found no .env. Check that the file is named exactly .env (not .env.txt or my-device.env) and that it sits in the agent's working directory or next to the executable. A systemd unit or launchd agent must set the working directory to the install folder.

`Exec format error`

The binary is built for a different CPU, for example the x86-64 build on an ARM board. Check the machine with uname -m (on a Raspberry Pi, dpkg --print-architecture), change the device's installation platform to match, and install the right binary. See Pick the right binary and Raspberry Pi.

The agent starts but the device never turns green

Usually the device token in .env is wrong or has been replaced: pressing Generate Setup Commands mints new tokens, and the old config stops working once the new one is installed. Download the config again, or rerun the install command. If the token is right, check that the machine can reach the relay at the WEBSOCKET_URL in .env.

The device row shows a red shield

The account is over its plan's device limit, so the relay refuses the connection. Remove a device you no longer use, or move to a larger plan.

It connects, then drops again and again

Something between the machine and the relay is interrupting the outbound connection, typically a firewall or proxy. Allow outbound HTTPS and WebSocket traffic to the relay.

The terminal opens and closes straight away

The browser terminal logs in through the machine's own SSH server. Check that SSH is running (systemctl status sshd, or ssh on Debian and Raspberry Pi OS), then re-enter the SSH username and password in the device sheet.

A file operation is refused

The path is outside ALLOWED_FILE_PATHS in the agent's .env. Add it to the list, or set ALLOW_ALL_PATHS=true, and restart the agent.

The install command no longer works

Install links expire after 7 days. Press Generate Setup Commands for a new one. The Update and Uninstall commands never expire.

`this command must run as root`

The root install command was run without root. Pipe it to sudo sh as shown in the panel, or switch the privilege selector to Non-root.

`sudo needs a password but there is no terminal to ask on`

The script needs sudo but runs somewhere it cannot prompt, such as an automation tool. Run sudo -v first so sudo does not need to ask, or use the Non-root install.

Windows: the agent cannot find `.env`

Notepad probably saved it as .env.txt. Turn on file name extensions in File Explorer and rename it to exactly .env. See Install on Windows.

macOS refuses to run the binary

A binary downloaded through a browser is quarantined by Gatekeeper, and macOS says it cannot verify the developer. Clear the attribute:

xattr -d com.apple.quarantine ~/clavda/clavda-client

ESP32 does not connect

Open the USB serial monitor at 115200 baud, with Tools → Core Debug Level → Info in the Arduino IDE. The library logs when it reaches the relay, why the relay refused it, or that it found no credentials. Then check:

Wi-Fi. The board must join a 2.4 GHz network. Check the name and password in the sketch.
No credentials: add clavda_device.h from the console. The sketch was built without the device file. Put clavda_device.h next to the sketch, or in include/ for PlatformIO.
A red shield on the device: the account is over its device limit, as above.