Troubleshooting

Start with the component that reports the failure. Do not rotate certificates or reset a daemon until basic connectivity and access assignments have been checked.

The target is not listed

On the workstation:

nk status
nk ls

Check that the identity is a member of the correct workspace and that the target principal is assigned to the user, team, or service account.

The daemon is offline

On the target server:

sudo systemctl status nokkud
sudo journalctl -u nokkud -n 100 --no-pager

Check the configured API URL, outbound network access, and whether the daemon was rejected or reset by the core.

The embedded SSH server is not listening

Check that the daemon is running and listening on its SSH port:

sudo systemctl status nokkud
sudo journalctl -u nokkud -n 100 --no-pager
sudo ss -lntp | grep -E '4022|nokkud'

The default listen address is :4022. The daemon must run as root so sessions can be dropped to the target user’s privileges. If nothing is listening, check the configured --ssh-addr and that the firewall allows the port.

No principal is authorized

Check the cached principal map and the daemon output:

sudo cat /var/lib/nokkud/cache.json
sudo journalctl -u nokkud -n 100 --no-pager

cache.json holds the subject UUIDs allowed for each Linux username. If the expected UUID is absent, verify the target assignment and wait for the daemon to reconnect.

The certificate cannot be refreshed

On the workstation:

nk login
nk status

The core must be reachable to issue a new certificate. Offline mode can reuse cached data and an existing certificate, but it cannot refresh either one.

All endpoints failed

nk proxy could not connect to any endpoint synchronized for the target. Check that the target is running, that the daemon’s embedded SSH server (default port 4022) is listening, and that firewalls allow the workstation to reach the configured endpoint.

TPM and the SSH identity

nk doctor reports the enrolled SSH identity and whether a TPM is available. With --key-type tpm, the SSH identity is TPM-backed: nokku.pub exists but no private key file does, and nk proxy serves the private key over the embedded SSH agent (~/.config/nk/agent.sock).

If the TPM becomes unavailable after a TPM-backed identity was enrolled (for example after a firmware update or when a VM loses its virtual TPM), nk refuses to silently downgrade to a software key. It fails with an error naming ~/.config/nk/nokku.pub; remove that file and run nk login again to re-enroll.

Reset and re-enroll

Only do this when the daemon’s local enrollment state is unusable:

sudo nokkud reset
sudo nokkud --enroll <NEW-TOKEN>

X.509 failures

Check that:

• An active X.509 CA exists in the workspace.
• The selected key type is allowed by the CA.
• The requested usage and TTL are allowed.
• The application trusts the CA certificate written by nk cert issue.
• The certificate SAN matches the hostname, IP, email, or URI used by the application.