Raspberry Pi Troubleshooting: Find the Cause by Symptom¶
Start with what your Raspberry Pi can still do. If it cannot reach a login, follow the boot checks below. If you can open a terminal locally or over SSH, use the matching diagnostic commands and follow the result to the next step.
Choose your symptom¶
- No boot, a rainbow screen, or repeated restarts. Record the screen message and LED pattern, then check power and boot media.
- Low-voltage warning, overheating, or sudden slowdown. Compare current temperature and firmware flags.
- Wi-Fi, Ethernet, or SSH fails. Identify whether the failure is connection, addressing, name resolution, or authentication.
- No space left, read-only storage, or I/O errors. Check the affected filesystem and preserve important data.
- An update fails or the display stays blank. Follow the package error or establish whether Linux has booted.
- GPIO or USB hardware does not respond. Check device discovery and wiring before changing configuration.
Commands labelled on the Pi need a running Linux terminal. SSH commands labelled on the client run on your other computer. Keep a working SSH session open while testing another connection.
Boot Problems¶
Cannot Boot from SD Card¶
- Record your exact Pi model, power supply, boot media, LED pattern, and anything shown on the display. Count long and short flashes separately.
- With power disconnected, check that the card is seated and the display is on the intended input. Disconnect optional peripherals for a simpler test, following their shutdown instructions first.
- Try a known-good supply and cable suitable for your model. A power LED alone does not confirm that the supply remains adequate during startup.
- If the card contains important files, preserve it. Write a board-compatible Raspberry Pi OS image to a spare card, let Imager verify it, and test that card.
If the spare card boots with the same supply and display, investigate the original installation or media. If it also fails, compare the board, supply, and boot diagnostics. A spare-card result narrows the investigation without proving which component failed.
Use the first-install guide for writing and verifying the spare card. The official hardware documentation explains LED codes and HDMI boot diagnostics for supported models. Install with Imager · Official bootloader diagnosis
Boot to Rainbow Screen (No OS Load)¶
A persistent rainbow screen or black display needs a second check. Look for the Pi in your router's connected-device list and try a known working SSH login.
- SSH succeeds — Linux has reached remote login. Continue with the display checks.
- SSH fails — This can also be a network or SSH setup failure. Record boot messages and LED codes, then follow the spare-card check above.
On models with two micro-HDMI ports, use HDMI0 for the first display test; check the board's connector labels. Connect a known-good cable and select the correct monitor input before booting.
Kernel Panic or Boot Loops¶
Photograph the complete panic message, including the lines before the final error. Note whether the loop began after an update, a new peripheral, a boot-file edit, or a power-supply change.
- A root-device or filesystem error points toward boot storage, its connection, or boot configuration.
- Restarts that coincide with a USB device or workload need a power-path check too.
- If the failure began with one recorded configuration edit, restore that edit using your local recovery method.
Protect data on the original card before repair or reinstallation. Use the filesystem recovery checks when storage errors appear. Once the Pi can boot, use the slow-boot guide to investigate startup delays.
Power Issues¶
Under-voltage Warning¶
On the Pi, take a snapshot while the symptom occurs:
Paste the first result into the decoder. 0x50000 records historical undervoltage and throttling; 0x50005 also has those current flags. The history flags alone do not date the event. Decode your reading and check the power path
If undervoltage is active, shut down cleanly before changing power cables or attached hardware. Check the supply's output capability, cable, connectors, and USB load against your board's requirements, then repeat the same workload. A powered USB hub may help with peripheral load. Official power requirements
Overheating and Thermal Throttling¶
Compare temperature with the firmware flags above during your ordinary workload. A throttling flag by itself does not identify heat as the cause. Pi model, enclosure, room temperature, and workload affect the readings.
Check heatsink contact, airflow, and fan operation. Follow the fan's documented connector and voltage requirements. Use the temperature guide for thermal limits, Pi 5 fan behaviour, and a bounded observation log. Temperature commands and cooling checks
Network Problems¶
Wi-Fi Not Working¶
On the Pi, inspect NetworkManager and the actual interface names:
- Wi-Fi radio disabled — Check whether that was intentional, then use the network guide's Wi-Fi setup steps.
- Device disconnected — Inspect the saved profile, SSID, authentication, and country setting before reconnecting.
- Device unavailable or unmanaged — Check the device's reported reason and which network manager owns it.
- Connected, but websites fail — Continue with the route and DNS checks below.
If nmcli is missing, identify the OS and active network manager first. On NetworkManager-based Raspberry Pi OS, use the guide's failure-specific steps and keep a recovery connection available when applying changes. NetworkManager results and recovery · nmcli reference
SSH Connection Failed¶
On the client, replace the username and address with your own:
Read the exact error before changing the Pi:
- Could not resolve hostname — Check the name or use the current IP from the router. Name resolution can fail while the Pi remains reachable by IP.
- Connection timed out or No route to host — Check the Pi's address, power, network path, and any isolation or firewall rules. These errors alone do not prove SSH is disabled.
- Connection refused — Check the destination and port, then inspect the SSH service on the Pi through local or alternate access.
- Permission denied — The SSH service responded. Check your username, selected key, and allowed authentication method.
- REMOTE HOST IDENTIFICATION HAS CHANGED — Verify the Pi's identity through a trusted local or alternate path before updating the client's saved key.
If you can open a terminal on the Pi, inspect its service:
For the standard service setup, active means it is running and enabled means it starts at boot. Follow the settings lesson to enable it when needed, or the access lesson for key and host-identity recovery. Enable SSH and test a login · SSH access and recovery
Ethernet Connection Issues¶
On the Pi, inspect addresses and routes, then test system name resolution:
Check the Ethernet interface identified by nmcli device status. If there is no carrier, compare the cable, router port, and link state. If the interface has no usable address, inspect its connection profile and DHCP result. If the route is missing, investigate the selected connection before assigning a static address.
If getent fails, inspect the active DNS configuration and network path. If it succeeds but a website fails, continue with that application's error, proxy, TLS, or server response. The networking guide explains how to interpret each stage. Address, route, and DNS diagnosis
Storage Issues¶
Running Out of Space¶
On the Pi, inspect the affected path. Replace / if the failing application writes to a separate mounted drive.
If capacity is full, identify the application or directory using the space. If inodes are full, many small files can prevent new files even when bytes remain available. Start with the project or log directory involved, checking its retention and backup before deleting anything. Storage inspection and low-space diagnosis
File System Corruption¶
For Read-only file system, I/O errors, or missing files, first inspect the mount state and recent kernel messages on the Pi:
If the journal reports storage I/O or filesystem errors, stop unnecessary writes and arrange data recovery. A deliberate OverlayFS setup can also make changes appear temporary; check the actual mounts before deciding the storage is damaged. OverlayFS mount diagnosis
For an offline check, shut down, attach the media to another Linux computer, identify the exact disk and filesystem, and copy or image important data first. Ensure the affected partition is unmounted before using the filesystem-specific repair tool. On ext4, e2fsck repairs can change data, and results from a mounted filesystem are unreliable. If errors suggest failing media, repeated repair attempts can make recovery harder. Storage identification and backups · e2fsck manual
Application and Software Issues¶
Package Manager Errors¶
Keep the exact APT error and identify its stage. On the Pi, these commands inspect free space and incomplete package state:
- Failed to fetch or name resolution error — Check connectivity and DNS before package repair.
- No space left on device — Follow the storage checks first.
- Unable to locate package — Check the package name, OS release, architecture, and configured repositories.
- Interrupted dpkg or unmet dependencies — Use the package guide's targeted recovery and review the proposed changes.
If another package operation is active, let it finish. Preserve its error output before retrying. APT failure stages and recovery
Display and Graphics Issues¶
If SSH works while HDMI is blank, investigate display output. Check monitor input, cable, adapter, and the board's HDMI port labels. If the desktop is accessible on another display, use its display settings to select a supported mode.
A Lite image provides a terminal environment. Check which image you installed before expecting a desktop. On current Raspberry Pi OS, follow the documented desktop/KMS display configuration for the board and release. Keep a backup and an alternate login before changing boot files. Official display configuration
Hardware Problems¶
GPIO Pin Not Working¶
Power down before changing wiring. Confirm the board's physical pin number, BCM GPIO number, ground, voltage, and the peripheral's required interface. GPIO logic is 3.3 V; keep motors and other loads on suitable driver circuitry.
Inspect available GPIO chips and line ownership when the gpiod tools are installed on the Pi:
Chip numbers and command syntax vary by board and libgpiod version. Check the installed tool's help and the course's line-discovery steps before requesting a line. If a line is already owned, identify its consumer before trying to use it. The LED lesson provides a known circuit, resistor, and explicit output control. GPIO discovery and LED circuit
USB Devices Not Recognized¶
On the Pi, list USB devices if lsusb is installed, then inspect a bounded kernel log:
- Device absent from the list — Compare a known data-capable cable, port, and the device's mode or power requirements.
- Device listed, but the application cannot open it — Investigate its driver, permissions, and device node.
- Repeated disconnects or resets — Compare kernel messages with power warnings and the cable connection.
Use a suitable power supply or powered hub when the peripheral requires it. If a PC is trying to detect the Pi itself as a USB Ethernet gadget, follow the controller-to-host checks in the gadget guide. USB gadget not detected or usb0 missing
Final Troubleshooting Steps¶
After one targeted change, repeat the original check and test the actual task. Confirm that a new SSH login, file save, display session, or peripheral operation succeeds. Record the outcome and restore the change if it causes a regression.
When asking for help, include the Pi model, OS release, exact error, what changed before it failed, and the checks already tried. Review logs for Wi-Fi names, addresses, usernames, and tokens before sharing them. Never include passwords or private keys.
For a system that works but runs slowly, continue with the performance guide. For first-login problems, use the headless setup troubleshooter. Performance diagnosis · Headless setup checks · Raspberry Pi forums