# Troubleshooting

> Fixes for the most common problems when signing in, connecting, and running the daemon.

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.

```bash
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 `nk` points at the right Nokku. `nk doctor` shows the address.
- If Nokku can't be reached, `nk ls` shows your last saved list, which might be outdated. `nk doctor` tells 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 `nokkud` running 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:

```bash
nk logout && nk login
```

On Linux, also check that your user is in the `tss` group, see [Connect to servers](/docs/getting-started/connect#where-your-key-lives).

### "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

```bash
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:

```bash
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:

```bash
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 sync` logs in as `root` with your own SSH setup. Check that `ssh root@<server>` works on its own.
- If `sshd` rejects the new config, `nk sync` puts every file back as it was. The error shows what `sshd` complained about.
- It refuses to change a server whose `sshd` config is already broken. Fix that first with `sshd -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](/docs/self-hosting/deploy#first-sign-in).

### "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-owner-lost-every-passkey). The sign-in link works with SSO required.

## On a self-hosted core

- Check that `https://<your-nokku>/healthz` answers.
- If `nk` or `nokkud` can'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](/docs/self-hosting/deploy#option-3-the-binary).
- If `nk` says "this machine does not trust the certificate", the core's certificate comes from a private CA. Pass that CA with `--ca-file` to `nk`, and with `NOKKUD_CA_FILE` to `nokkud`. Both keep it. See [Connect nk and nokkud](/docs/self-hosting/deploy#connect-nk-and-nokkud).

## Still stuck?

Run the failing command again with `--debug` for detailed logs, and [contact support](mailto:support@mizuchi.dev) with the output.
