Start with nk doctor on your laptop. It checks your sign-in, the connection to Nokku, your SSH setup and the TPM, and most of the time it tells you exactly what to fix.
nk doctor
nk doctor --fix # repairs local files and permissions
If that doesn’t help, find your symptom below.
On your laptop
A server is missing from nk ls
- Check that someone granted you an account on it. Without a grant, it doesn’t show up.
- Check
nkpoints at the right Nokku.nk doctorshows the address. - If Nokku can’t be reached,
nk lsshows your last saved list, which might be outdated.nk doctortells you whether the connection works.
“you no longer have access to this server”
Your access was removed, or the server was deleted. Run nk ls to see what you can reach now.
“cannot reach …”
nk couldn’t connect to the server directly, and not through the relay either.
- Is the server running? For daemon servers, is
nokkudrunning on it (see below)? - For servers set up with
nk sync, there’s no relay. Your laptop must be able to reach the server’s SSH port directly. - For daemon servers, the relay needs a connection to Nokku. If Nokku is unreachable, only direct connections work.
“no valid certificate …”
nk couldn’t get a fresh certificate. Usually your sign-in expired. Run nk login and try again.
The TPM stopped working
After a firmware update, or when a virtual machine loses its virtual TPM, your machine identity changes. Sign out and in again:
nk logout && nk login
On Linux, also check that your user is in the tss group, see Connect to servers.
“this key is not the one this nk session signed in with”
Your SSH key changed since you signed in, for example because you switched to a security key or the TPM. A sign-in only gets certificates for its own key. Run nk logout, then nk login.
On a daemon server
The server shows as offline
sudo systemctl status nokkud
sudo journalctl -u nokkud -n 100 --no-pager
- Not enrolled yet? The service stops right away with an error until you run
sudo nokkud enroll. - Waiting for approval? Someone with the editor role or higher needs to approve the server in the web app, unless the enroll token approves automatically.
- Rejected? If an admin rejected the daemon, it stops. Enroll it again with a new token.
- No connection? The daemon needs outbound HTTPS to Nokku. Check proxies and egress firewalls.
Direct connections don’t work, the relay does
Connections still succeed, just through Nokku. To connect directly, check that nokkud listens on port 4022 and that the firewall allows it:
sudo ss -lntp | grep 4022
Someone with a grant is denied
The server checks its local copy of the access list. It updates as soon as the daemon is connected, so check the daemon is online (see above). The log shows each denied login and why:
sudo journalctl -u nokkud -n 100 --no-pager
On a server set up with nk sync
Nobody gets in after a CA rollover
These servers trust only the CA key they were given. Run nk sync <server> on each one. The Certificate authority page lists the ones that still need it.
An account is missing in the web app
A server reports its accounts when you run nk sync. Run it again after you add an account on the server. Only login accounts are reported, not system accounts without a shell.
nk sync fails
nk synclogs in asrootwith your own SSH setup. Check thatssh root@<server>works on its own.- If
sshdrejects the new config,nk syncputs every file back as it was. The error shows whatsshdcomplained about. - It refuses to change a server whose
sshdconfig is already broken. Fix that first withsshd -t.
Signing in
The sign-in link did not arrive
- Give it a minute and check spam. Links only work for a short time.
- Asking again right away sends nothing new, the first link is still on its way. Wait a few minutes before you ask for another.
- The form always says a link is on its way, also for an address that has no account here. Check the address, or ask an admin whether you were invited.
- On a self-hosted core without email set up there are no links. Sign in with a passkey or your identity provider, or ask the owner for a new invitation.
“This link is invalid or expired”
Links work once and only for a short time. Ask for a new one on the sign-in page. For an invitation, ask whoever invited you for a fresh link.
The owner lost every passkey
On the hosted service, ask for a sign-in link on the sign-in page. On a self-hosted core without mail, run nokku recover on the server. It prints a sign-in link for the owner, see Deploy the core.
“This account has been deactivated”
An admin switched your account off, or your identity provider did through SCIM. Ask them to reactivate it.
SSO sign-in fails
- Check the provider settings in the workspace: issuer URL, client ID and secret, and the redirect URI.
- Check the provider is enabled, and that Create accounts on first sign-in is on if you never signed in here before.
- With Require single sign-on on, passkeys and email links are rejected on purpose, except for the owner.
Locked out by required SSO
With Require single sign-on on, a broken provider keeps everyone out but the owner. The owner keeps their passkey and email links for exactly this.
- The owner signs in with their passkey or an email link, then repairs the provider or turns the requirement off until it works again.
- The owner lost every passkey too? See The owner lost every passkey. The sign-in link works with SSO required.
On a self-hosted core
- Check that
https://<your-nokku>/healthzanswers. - If
nkornokkudcan’t connect but the browser works, your reverse proxy probably doesn’t forward HTTP/2. Their error and the core’s log then say so. See Deploy the core. - If
nksays “this machine does not trust the certificate”, the core’s certificate comes from a private CA. Pass that CA with--ca-filetonk, and withNOKKUD_CA_FILEtonokkud. Both keep it. See Connect nk and nokkud.
Still stuck?
Run the failing command again with --debug for detailed logs, and contact support with the output.