Support · use at any stage

Troubleshoot by evidence

Something did not work. Resist the urge to reflash and hope. Find which layer failed, change one thing at a time, and write down what you observed. That habit is worth more than any single fix on this page.

Find the layer that failed

Work left to right. A layer can only be blamed if every layer to its left is proven good. A boot test before B passed is a wasted boot test.

A. Can the lab PC see the boot drive? It must appear in the PC's file manager or in Imager's storage list. If not, the problem is the card reader, the cable, the enclosure, the USB port, or the drive itself: nothing about the Pi matters yet.
B. Did Imager finish both Write and Verify? If Verify failed, the data on the drive is not trustworthy. Write again once; if it fails twice, change the cable, reader, or drive.
C. Does the firmware find the drive? Red LED steady, green LED blinking, something on the screen within 30 s. No green activity means the bootloader found nothing to boot: card seated? SSD in a blue port with the card slot empty? enough power?
D. Did Linux start and can you see it? Scrolling text then a desktop. A black screen with a blinking green LED is usually a display problem, not a boot problem: cable, HDMI0 vs HDMI1, screen input.
E. Is it the configuration? Everything boots but Wi-Fi, SSH, the keyboard layout or the hostname is wrong. These are fixable from the Pi in raspi-config; nothing needs reflashing.

Symptom table

Symptom	Layer	Most likely cause	What to do
Boot drive missing from Imager's storage list	A	Card reader, cable, enclosure, USB port, or the drive itself	Reseat or reconnect, try another port, reader or cable, check that the PC's file manager sees it, keep "Exclude system drives" ticked
Two similar drives in the list	A	Another USB drive still plugged in	Cancel, unplug everything but your drive, reopen the list
Verify fails	B	Bad card, reader, cable, enclosure, or failing SSD	Write once more; if it fails again, swap the hardware
Red LED on, no green blink, black screen	C	No bootable device found, or the drive is not powered or seated	MicroSD: reseat the card until it clicks. SSD: blue port, no card in the slot, correct power supply, try the other USB 3 port
You wrote an SSD, but `findmnt` says `mmcblk0p2`	C	A microSD card is also inserted and wins the boot order	Shut down, remove the card, reboot. (If your boot drive is the microSD card, `mmcblk0p2` is the correct answer.)
Older Pi 4 ignores the SSD	C	Early bootloader without USB boot	Update the bootloader (below)
Pi reboots randomly, lightning-bolt icon, USB devices vanish	C/D	Insufficient power, especially Pi 5 on 15 W with a USB SSD	Use the model's supply (27 W for Pi 5); check `vcgencmd get_throttled`
Green LED blinks, screen stays black	D	Wrong screen input, cable in HDMI1, cable plugged after power-on	Select the HDMI input on the screen; use HDMI0; connect the screen before power
Rainbow square stays on screen	D	Kernel not loading; often power or a corrupted image	Check power first, then re-image after a successful Verify
Symbols land on the wrong keys; password refused	E	Keyboard layout is not the physical keyboard's	`sudo raspi-config` → Localisation → Keyboard (log in with keys that are the same in both layouts first)
No Wi-Fi at all, `rfkill` says soft blocked	E	WLAN country not set	`sudo raspi-config` → Localisation → WLAN Country → CA
Wi-Fi network visible but will not connect	E	Wrong password, or enterprise network	Retype from the desktop network icon; enterprise networks need the desktop dialog, not Imager
`ping hostname.local` fails from the PC	E	Different networks, mDNS blocked, or duplicate hostname	Use the IP from `hostname -I`; check both machines are on the class network; rename the Pi if a classmate has the same hostname
`ssh` says "Connection refused"	E	SSH service not enabled	On the Pi: `sudo raspi-config` → Interface Options → SSH → Yes
`ssh` warns "REMOTE HOST IDENTIFICATION HAS CHANGED"	E	The Pi was re-imaged, so its key changed; the PC remembers the old one	On the PC: `ssh-keygen -R hostname.local`, then connect again
`apt update` fails with date or certificate errors	E	Clock wrong (no network time yet)	Connect to the network and wait a minute, or set the time: `sudo date -s "2026-08-31 15:00"`, then retry

Read `vcgencmd get_throttled`

The number is a set of flags. 0x0 is perfect. Anything else is evidence, not a verdict.

$ vcgencmd get_throttled
throttled=0x50000

Bit	Value	Meaning
0	`0x1`	Under-voltage right now
1	`0x2`	CPU frequency capped right now
2	`0x4`	Throttled right now
3	`0x8`	Soft temperature limit active right now
16	`0x10000`	Under-voltage has occurred since boot
17	`0x20000`	Frequency capping has occurred
18	`0x40000`	Throttling has occurred
19	`0x80000`	Soft temperature limit has occurred

0x50000 = 0x40000 + 0x10000: under-voltage happened at some point and the Pi throttled because of it, but it is fine right now. That pattern almost always means the power supply or the USB load. 0x80008 is heat, not power.

USB boot and the bootloader

Raspberry Pi 4, 400 and 5 boot from USB mass storage thanks to the bootloader in their EEPROM. Two things can get in the way.

A microSD card is present

The default boot order tries the SD card first. Remove the card. Changing the order is possible (sudo raspi-config → Advanced Options → Boot Order) but unnecessary if the slot is empty.

An early Pi 4 has an old bootloader

Pi 4 boards made before mid-2020 shipped without USB boot support. Check and update from a Pi that does boot (for instance from a microSD card):

$ vcgencmd bootloader_version
$ sudo rpi-eeprom-update        # shows CURRENT and LATEST
$ sudo rpi-eeprom-update -a     # install the latest, then reboot

Without any working system, use Imager: Choose OS → Misc Utility Images → Bootloader → USB Boot, write it to a spare microSD card, boot the Pi 4 from that card, wait for the green LED to blink steadily (the screen turns green), power off, remove the card, and try the SSD again. Ask the teacher before touching the bootloader; it is a one-time operation per board.

Network and SSH checks, in order

On the Pi: ip -brief address. Does wlan0 or eth0 have an address starting with 10., 172. or 192.168.? If not, the Pi is not on the network: go back to Network and Wi-Fi.
On the Pi: ping -c 3 raspberrypi.com. Works: Internet is fine. Fails but step 1 was fine: the class network has no Internet; apt will fail, everything local still works.
On the PC: ping -c 3 <the Pi's IP>. Fails: the PC and the Pi are on different networks (College Wi-Fi vs class Wi-Fi is the usual case).
On the PC: ping hostname.local. Fails while step 3 works: mDNS is blocked; use the IP address in ssh user@IP.
On the PC: ssh user@IP. "Connection refused": enable SSH on the Pi. "Permission denied": wrong username or password (remember the keyboard layout). Host key warning: ssh-keygen -R as in the table.

Before you ask for help

Bring evidence. The teacher can solve in one minute what takes ten without it.

Which layer (A to E) you got to, and what you observed at the one that failed: the exact message, the LED behaviour, the screen.
What you changed since it last worked, and what you already tried.
The output of vcgencmd get_throttled, findmnt -no SOURCE / and ip -brief address when the Pi boots at all.

Michel Paquette's Raspberry Pi OS setup notes collect fixes for recurring problems from past editions of this course (clock, gadget mode and more) and are worth a look before you re-image anything.