Troubleshooting node enrollment

Use this guide when the node never comes online, looks stuck during first connection, or starts from obviously stale config.

Check the intended network first

Confirm that:

• the node belongs to the intended workspace and network,
• the network still exists and was not replaced during setup,
• the onboarding action produced a fresh config for this exact node.

Check generated config and key freshness

Look for:

• stale WireGuard config copied from an older enrollment step,
• a public key mismatch between the UI and the live host,
• an interface config that was generated before the latest policy or gateway change.

Check basic connectivity from the endpoint host

Confirm the host can reach:

• the management service URL you actually published for this setup,
• the current gateway path for the network,
• the expected reverse-proxy or published domain instead of a stale direct endpoint.

Decide the next move

• If config is stale, regenerate it and re-apply it cleanly.
• If the network or workspace target is wrong, fix the target first instead of retrying blindly.
• If the host cannot reach the published path, move into Troubleshooting gateway health.