Node troubleshooting

Every ✗ and every failed step prints its own fix, and the same command run again continues from where the install stopped. Start with the line it printed. Below are the ones admins run into most.

A check says the disk is not empty

The disk has partitions, a partition table, a filesystem or a signature, and the installer never wipes a disk for you. If nothing on it matters, run sudo wipefs -a /dev/sdb for your disk. When the disk belongs to a ZFS pool, the line names the pool: destroy it first with sudo zpool destroy <pool>, which destroys every file on it. An LVM disk is named as such. Take its LVM off first: pvs /dev/sdb names its volume group, vgremove <group> destroys its volumes, then run pvremove /dev/sdb.

A check finds other software on the server

The node takes the whole server, so Docker, LXD, an Incus or cloudflared the installer did not put there, or another ZFS pool stops the install. The line lists each one with the command that removes it, such as apt-get purge docker-ce docker.io or snap remove --purge lxd. Remove them, or use a clean server.

Secure Boot or the kernel headers fail

The node builds its own ZFS module. Turn Secure Boot off in the firmware, or enroll the DKMS key: apt-get install dkms, then mokutil --import /var/lib/dkms/mok.pub, and confirm it at the next boot. For the headers: apt-get update && apt-get install linux-headers-$(uname -r); if apt still has none, apt-get full-upgrade and reboot into the newest kernel.

Outbound, TLS or the clock fail

• Outbound names each destination that did not answer. Allow outbound TCP to them, and UDP 7844 to Cloudflare's tunnel. What the server needs has the full list.
• TLS names the authority that signed what it got. Let api.detachbox.com and *.argotunnel.com through without TLS inspection.
• Clock: timedatectl set-ntp true, and let the server reach its NTP servers on UDP 123.

The disk holds a kept pool

An earlier node on this server was uninstalled with its pool kept, and the new install refuses that disk: a new node never takes over the old node's files. Give the new node another disk (lsblk -d -o NAME,SIZE,MODEL,SERIAL lists them), or, if nothing on the kept pool matters, run the command the line prints: its uninstall --confirm --destroy-pool destroys the pool with everything on it and removes ZFS and detachbox-node-host. Imported again to read its files, the kept pool shows in the check for other software: sudo zpool export boxes puts it back on its disk, and the uninstall command the line prints removes it.

The token is refused

A server has 7 days to enroll with a token, and after it enrolls the token takes reruns of that install for 7 more days.

• "The server does not know this token, or it expired": ask your detachbox contact for a new one.
• This token was already used by another machine: the line names that server's host name, address and time. A token belongs to the first server that enrolled with it. If that server is not yours, do not use the node and tell detachbox support at once; for another server of yours, ask for a new token.
• "The server has not finished setting up this node's tunnel and certificate": ask your detachbox contact for a new token, then run the command with it.
• "This token's node is live already": the token is spent on a live node. On the server that enrolled with it, the node is up; open https://my.detachbox.com. For another server, ask for a new token: each server needs its own.
• The server enrolled with another token: run the command with that one.

The command stops before its checks

• no answer from https://api.detachbox.com: the server needs outbound HTTPS (port 443). Run the same command again once it has it.
• this token downloaded node-host several times lately: wait the minutes it names, then run the same command again.
• the server asks this machine to slow down (429): run the same command again in a minute.
• The server is not Ubuntu 26.04 on x86_64, or the command did not run as root: the line says which.

The install's record does not read

/var/lib/detachbox-node/install/state.json is the install's record of what it did on the server. If the server lost power while it was written, the install and the uninstall both stop with does not read: without the record, neither knows what is the node's, and neither guesses. Send that line to your detachbox contact. To start over, take the node off by hand, as "Remove it by hand" on Remove the node lists, then sudo rm /var/lib/detachbox-node/install/state.json and run the install command again.

--destroy-pool leaves the disk

--destroy-pool wipes the disk only when everything on it is the install's. Two refusals come up most:

• The disk is not the disk the pool boxes was made on: the disk's name changed since the install, such as /dev/sdb becoming /dev/sdc. lsblk -o NAME,WWN,SERIAL finds the recorded disk under its name now. Or run uninstall --confirm without --destroy-pool, which leaves the disk and removes the rest.
• The disk or a partition "holds …, which this install did not put there", or carries another pool's ZFS label. If nothing on it matters, wipe it yourself with sudo wipefs -a /dev/sdb; uninstall --confirm without --destroy-pool removes the rest.

Another run is at work

Only one install or uninstall runs at a time. The message names that run's start and process. Follow it with sudo tail -f /var/lib/detachbox-node/install/install.log. If it is truly stuck, sudo kill <pid> stops it within seconds; then run the same command again.

A step fails

Before step 6, detachbox-node-host is not on the PATH yet: the checks run through the same install command with --check added, which changes nothing and spends no token.

• Packages: apt could not reach pkgs.zabbly.com, pkg.cloudflare.com or your apt mirror; the command with --check checks the way to them.
• OpenZFS: apt could not install what the build needs, or the release did not come from github.com and release-assets.githubusercontent.com; the command with --check checks the way there. A build cut short starts again from a clean tree. When DKMS fails, dkms status and /var/lib/dkms/zfs/2.4.4/build/make.log say why.
• Incus: sudo journalctl -u incus -n 50 shows what Incus said.
• The base image: its last lines name the part of the build that failed; it downloads from the hosts the command with --check checks.
• cloudflared and node-host: sudo journalctl -u detachbox-node-host -u cloudflared-detachbox -n 50 says why.
• The bring-up: after 10 minutes without node-host reached, the command points at the tunnel, which needs outbound TCP and UDP 7844. When the server stops the bring-up, the line says why and your detachbox contact sees it too. After 45 minutes without the node live, run sudo detachbox-node-host doctor, then the same command again to keep following.

The logs

What to send support

A failed install step reaches detachbox by itself, with your token. For anything else:

1. Once the node has enrolled, run sudo detachbox-node-host doctor --report. It sends doctor's result and the server's facts to detachbox. Before that, a failed step has reached detachbox already.
2. Write to support@detachbox.com, or open Support in the dashboard, with the line that failed and the last lines of the log: sudo tail -n 100 /var/lib/detachbox-node/install/install.log.