Worker installation problems
The install failed, or finished and produced nothing. What to check, in order.
Work down this list. Most installation problems are one of the first three.
The installer refuses to start
Run vapn doctor. It repeats the install-time checks against the
machine as it is now and names what failed, which is faster than guessing.
| Symptom | Usual cause |
|---|---|
| Docker not found | Docker is not installed, or the installing user is not in the docker group. |
| Insufficient disk | Less than 2 GB free. Check /var/lib/docker specifically, not just /. |
| Cannot reach the platform | Outbound HTTPS blocked. See Network restrictions. |
| Unsupported architecture | The image is published for common Linux architectures. An unusual one is not supported. |
The token is rejected
- It has already been used. A token enrols one worker. Enrolling a second machine needs a second token.
- It was mistyped. Tokens are long; paste rather than retype.
- It has been revoked. Staff can revoke an unused token. Ask for a new one.
Tokens are shown once and are not recoverable. If you no longer have it, request a new one rather than looking for the old one.
The name is rejected
Lowercase letters, digits and dashes, three to forty characters. No spaces, no slashes, no capitals, no underscores. The rule is narrow because the name ends up in command output and in the fleet register, where anything else is a paste that breaks later.
The install succeeded and the worker does nothing
This is the common one, and it usually is not an install problem at all.
vapn status: is it enrolled, and when did it last upload?- If enrolled and never uploaded, the worker is probably unable to send ICMP. See Worker connectivity. This is the single most common cause of a worker that looks healthy and contributes nothing.
- If it has uploaded but nothing appears anywhere, that is expected for a new worker: influence is earned rather than granted at enrolment. See How workers contribute to monitoring.
Starting again
vapn uninstall then reinstall, with a fresh token. Uninstalling properly tells the
platform the worker is going, which retires it cleanly instead of leaving a silent entry in the
register.
Was this page helpful?