A node you enrolled is not listed

Symptom

The installer finished on the machine, and Nodes in the dashboard does not list it — or lists it and it never becomes ready. GET /api/v1/nodes does not return it either, so this is not a display problem.

Diagnose

1. Is the container runtime running on the machine?

   docker info

   Expect a server section with a version. Cannot connect to the Docker daemon means the agent has nothing to drive, and it will not report ready.

2. Did the agent start, and what did it say?

   sudo journalctl -u odysseus-agent --since "10 minutes ago"

   Expect a start-up line followed by a successful registration. Authentication failures, connection timeouts and runtime API errors each name themselves here.

3. Was the enrolment token already used? Tokens are single-use and expire. A second run of the same install command is refused, and that refusal looks like a silent failure if nobody reads the log.

4. Can the machine reach the control plane at all? The agent maintains an outbound connection; a node that enrols and then goes quiet is usually egress, not enrolment.

Resolve

• Runtime not running: start it, then restart the agent. The agent does not need re-enrolling.
• Token spent or expired: issue a new one from Nodes → Enrol a node and run the fresh command. Do not re-run the old line: it carries the consumed token.
• Egress blocked: open outbound HTTPS to the control plane. Nothing on the platform side can compensate for a machine that cannot call out.
• Enrolled under the wrong tenant: a node belongs to one tenant and does not move. Remove it and enrol it again from the right one.

Prevent

Enrol from the dashboard at the moment you run the command, so the token is fresh, and check the node reaches ready before you close the shell. A machine that is going to fail enrolment fails within about a minute, and the log line that says why is only easy to find while it is the last one.