Skip to content

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

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

  1. Record your exact Pi model, power supply, boot media, LED pattern, and anything shown on the display. Count long and short flashes separately.
  2. 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.
  3. 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.
  4. 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:

vcgencmd get_throttled
vcgencmd measure_temp

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:

1
2
3
4
nmcli device status
nmcli radio wifi
ip -brief address
ip route
  • 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:

ssh -o ConnectTimeout=10 your-user@PI_ADDRESS

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:

systemctl is-active ssh
systemctl is-enabled ssh

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:

1
2
3
ip -brief address
ip route
getent ahosts www.raspberrypi.com

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.

df -hT /
df -i /

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:

findmnt -no SOURCE,FSTYPE,OPTIONS /
journalctl -k -b --no-pager -n 60

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:

df -hT /
dpkg --audit
  • 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:

gpiodetect
gpioinfo

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:

lsusb
journalctl -k -b --no-pager -n 60
  • 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

Donate