Utility · use it before asking for help

Troubleshoot by layer

Week 2's ladder found boot problems. This week's failures happen later: a connection is refused, a key is ignored, a rule blocks you. Same discipline, new ladder: find the first layer that fails and fix that one.

Find the layer that failed

Work left to right. "Connection refused" or a timeout is A, B or C. A password or key complaint means A–C passed and the problem is D.

A. Does the network reach the Pi? From the lab PC: ping lastname-pi.local. No answer: same network? Try the IP from hostname -I typed at the Pi. This layer is Week 2's network section, unchanged.
B. Is the service listening? At the Pi: ss -tlnp. No sshd on 22 or wayvnc on 5900 means the service is off; enable it (SSH and VNC both live in raspi-config → Interface Options).
C. Does the firewall allow the port? sudo ufw status verbose. Active with no rule for the port explains a refusal from outside while the service listens happily inside.
D. Does authentication succeed? Only now do keys, passphrases and passwords matter. ssh -v (one v) narrates which keys were tried and why login fell back to a password.

Symptom table

Symptom	Layer	Most likely cause	What to do
`apt update`: certificate or "not valid yet" errors	–	Pi clock behind reality	Check `date`; get online for network time or set the date by hand; see the clock callout
`apt install ufw`: package not found	–	Stale catalogue	`sudo apt update` first, then install
`apt`: "could not get lock"	–	Another apt is running (often the desktop updater)	Wait for it to finish; do not delete lock files
SSH asks for the Pi password despite `ssh-copy-id`	D	Key not installed for that user, or wrong permissions	Rerun `ssh-copy-id` as the right user; on the Pi: `chmod 700 ~/.ssh; chmod 600 ~/.ssh/authorized_keys`; then `ssh -v`
SSH asks for a passphrase every time	D	That is your key's passphrase, working as designed	Normal. To stop retyping it this session: `ssh-add` once (the agent remembers it)
`Permission denied (publickey)` from GitHub	D	Public key not added on the site, or wrong remote form	`ssh -T git@github.com` to test; re-add the `.pub` line under Settings → SSH keys; remote must start `git@github.com:`
SSH worked, then "connection refused" right after `ufw enable`	C	Firewall enabled before the port 22 rule	See locked out below
VNC viewer: connection refused or timeout	B/C	Service off, or no 5900 rule	`ss -tlnp \| grep 5900` decides: no listener → enable VNC; listener → `sudo ufw allow 5900/tcp`
VNC connects, black or tiny desktop	–	Headless: no resolution set	raspi-config → Display Options → VNC Resolution, reboot; see headless
VNC login rejected	D	Wrong credentials type	Use the Pi account username and password, not your SSH key passphrase or GitHub login
Everything network-y fails at once	A	Wi-Fi dropped or wrong network	Back to Week 2's network checks, then re-test SSH

Locked out by UFW

You enabled the firewall over SSH before allowing port 22, and now every connection is refused. Nothing is damaged; the fix takes one minute at the Pi's own keyboard:

$ sudo ufw allow ssh
$ sudo ufw status verbose      # confirm 22/tcp ALLOW IN appears

Then reconnect from the lab PC. If you cannot reach the Pi's keyboard (headless at home), plug in a screen and keyboard once, or use the USB gadget link, which UFW's incoming rules do not affect on a fresh setup. The nuclear option, sudo ufw disable, also works; re-enable after adding the rule.

Key problems up close

$ ssh -v username@lastname-pi.local 2>&1 | grep -E "Offering|Authentications|Accepted|denied"
debug1: Offering public key: /home/username/.ssh/id_ed25519 ED25519
debug1: Authentications that can continue: publickey,password

Offering public key then a password prompt: your key was tried and rejected, so the Pi does not have its public half (or permissions block authorized_keys). Fix on the Pi side.
No "Offering" line: the client did not find a key; wrong file name or wrong machine. Generate or specify with ssh -i.
On the Pi, cat ~/.ssh/authorized_keys should show one line per machine you added, ending with the comment you set (lab-pc). No line, no login.

Before you ask for help

Bring evidence, and the teacher can help in one minute instead of ten. For this week that means:

Which layer (A, B, C, D) you got stuck at, and the command outputs that prove the earlier layers pass.
For SSH problems: the grep-filtered ssh -v output above.
For firewall problems: sudo ufw status verbose, copied exactly.
What you changed since it last worked, and what you already tried.

Recurring stubborn cases (clock, gadget mode) are collected in Michel Paquette's Raspberry Pi OS setup notes.