AKGuidebooks Home Server Admin

When things go wrong

Troubleshooting#

Find the message you see, or press / and search for words from it.

Golden rules: read the exact error message; change one thing at a time; don't reinstall or erase anything to "fix" a connection problem.

First: which kind of problem?#

flowchart TD
  A["Can't connect with ssh"] --> B{"What does it say?"}
  B -- "Could not resolve hostname" --> N["Name problem<br/>see: Could not resolve"]
  B -- "Connection timed out" --> T["Network / server off<br/>see: timed out"]
  B -- "Connection refused" --> R["SSH not running<br/>see: refused"]
  B -- "Permission denied" --> P["Key problem<br/>see: Permission denied"]
  B -- "REMOTE HOST IDENTIFICATION<br/>HAS CHANGED" --> H["Reinstalled server<br/>see: host changed"]

Connecting#

Could not resolve hostname homeserver#

The name can't be found.

  • At home: try homeserver.local, or the number from your notebook.
  • Away from home: .local names never work away from home. Is Tailscale on on this device? Check its icon or app.
  • Still stuck: on the server, tailscale ip -4 gives a 100.x.x.x number. Use that.

Connection timed out#

Your device can't reach the server at all.

  1. Is the server on and plugged in? Lid closed without Chapter 13? Then it's asleep.
  2. Is the address right? Addresses can change after a router restart. Use the name, or reserve the address (Chapter 6).
  3. Away from home: is Tailscale connected on both devices? Check the Tailscale Machines page.
  4. Did the server lose Wi-Fi? See Wi-Fi stopped working.

Connection refused#

The server is reachable but SSH isn't running. At the server's keyboard: sudo systemctl start ssh.

Permission denied (publickey)#

The server doesn't accept this device's key.

  • Are you on a new device? Add its key (Chapter 10).
  • Is your shortcut pointing to the right key? Run ssh -G homeserver | grep -i identityfile.
  • Wrong username? Check the User line in your ~/.ssh/config.

WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!#

Normal after you reinstall the server, because it has a new identity. If you did not reinstall, stop and find out why. If you did, remove the old record on your Mac or PC:

Type on: your Mac or PC
ssh-keygen -R homeserver
ssh-keygen -R homeserver.local

Then connect again and answer yes.

It asks for my key passphrase every time#

  • Mac: ssh-add --apple-use-keychain ~/.ssh/id_ed25519_homeserver, and make sure your config has UseKeychain yes (Chapter 7).
  • Windows: the ssh-agent service isn't running; redo Chapter 8, step 6.

command not found for a command from this guide#

Check the prompt: you're probably typing in the wrong place. Windows commands (Get-Service, notepad…) typed on the server fail, and so do server commands typed on Windows. See Where am I typing?. Type exit to leave the server.

Server problems#

alex is not in the sudoers file#

You set a root password during install. At the server's keyboard, log in as root with that password, then:

Type on: the server, as root
usermod -aG sudo alex

Log out, log in again as alex.

Wi-Fi stopped working#

At the server's keyboard:

Type on: the server
ip -brief address
sudo ifup wlp2s0

(Your Wi-Fi name may differ from wlp2s0; it's the one that starts with wl in the first command.)

  • If you edited Wi-Fi settings recently, a typo is the usual cause. Run sudo journalctl -b -u networking and read the last lines.
  • Moved the server to a new Wi-Fi network? The installer only saved the old one. Easiest fix: plug in an Ethernet cable.

Could not get lock /var/lib/dpkg/lock#

Automatic updates are running. Wait 5–10 minutes and try again. Don't delete lock files.

The server won't start after I added a hard drive#

Usually an /etc/fstab line without nofail, or a typo. At the server's keyboard, it may show an emergency mode prompt. Type your password, run nano /etc/fstab, put # in front of the new line, save, and run reboot. Then redo Chapter 15, step 5 carefully.

Disk full#

Type on: the server
df -h
sudo du -sh /srv/* /var/log /home/* 2>/dev/null

The second command shows which folders are big.

File sharing#

Finder / Explorer can't connect to the share#

  1. Does ssh homeserver work from the same device? If not, fix that first (above).
  2. On the server: systemctl is-active smbd should say active, and testparm -s should show [files].
  3. Login rejected? Use the Samba password, not your login password. Reset it with sudo smbpasswd -a alex.
  4. Using homeserver.local (no Tailscale)? You need the home-network firewall rule (Chapter 16 tip).

Security layer#

channel 2: open failed: administratively prohibited when opening a tunnel#

Tunnels are switched off. Check sudo sshd -T | grep allowtcpforwarding says local (Chapter 28).

SSH stopped working away from home after tightening the firewall#

Use ssh homeserver-remote (Tailscale). Plain homeserver.local only works at home, and after Chapter 29 SSH is only allowed from your home network and Tailscale.

I banned myself with Fail2ban#

From another device or the server's keyboard: sudo fail2ban-client status sshd to see the address, then sudo fail2ban-client set sshd unbanip ADDRESS.

Cockpit login fails#

Use your server account password (the sudo one), not your key passphrase. Root can't log in.

gpg: problem with the agent or no passphrase prompt#

Run export GPG_TTY=$(tty) in the same window first, and keep --pinentry-mode loopback in the command (Chapter 33).

AI#

error while loading shared libraries: libgomp.so.1#

The engine needs one extra package: sudo apt install libgomp1.

llama-model is not active#

Read why:

Type on: the server
sudo journalctl -u llama-model -n 50 --no-pager
Message contains Fix
No such file or failed to load model The path in /etc/ai-runtime/model.env doesn't match the file name. Compare with sudo ls /srv/ai/models
Permission denied Redo the chown/chmod lines in Chapter 20
out of memory, or the service is killed Use the smaller model, or lower --ctx-size to 1024

/health says the model is loading, or curl gets no answer#

Wait a minute after a restart: loading takes time. The first question after a start is also slow (about a minute).

The answer is empty#

Use the address /v1/chat/completions, not /completion.

Answers stop in the middle#

Raise max_tokens in the request (or in the chat page settings). In ask-pages, change max_tokens: 400.

bind: Address already in use when opening a tunnel#

An old tunnel is still open. Close that terminal window, or pick another number on your side.

The agent dashboard says "origin rejected" or won't load#

Use exactly -L 18765:127.0.0.1:8097 and open http://127.0.0.1:18765. Other port numbers are refused.

aisystem stops when I log out#

Linger is off: sudo loginctl enable-linger $USER, then systemctl --user enable --now aisystem.

Recoll finds nothing in a PDF#

Either the PDF is a scan (no text inside), or poppler-utils wasn't installed when you indexed. Install it, then run recollindex -c ~/.recoll-docs again.

Installing#

USB stick doesn't appear at startup#

Recreate it with Etcher (Chapter 2); try another USB port; on a PC, enable USB boot in the setup screen.

Keyboard / trackpad don't work in the installer#

Use a USB keyboard. Common on some MacBooks.

No Wi-Fi in the installer#

Use an Ethernet cable or USB-Ethernet adapter. Wi-Fi often works after installation.

Computer restarts into the installer again#

Remove the USB stick and restart.

Made by Anish · 2026