Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 37 ยท Projects and Practice

Troubleshooting Your Pi: A Systematic Guide

Diagnose Raspberry Pi problems step by step: LED codes, power and SD card faults, no network, SSH refused, services failing, GPIO permission errors, plus a runnable decision-tree helper.

Every Pi owner meets the same problems: it will not boot, it will not connect, the script runs by hand but not as a service. The difference between a beginner and an expert is not knowing every answer but following a method: observe, narrow down, change one thing, check. This lesson gives you that method and a set of checklists for the most frequent faults.

Hardware faults and logs are specific to a real Pi, so commands are read-only. The runnable blocks encode the troubleshooting logic as code, which is a good way to learn it.

The method

  1. State the problem exactly. "It does not work" is not a symptom. "SSH says connection refused" is.
  2. Find the layer. Power, storage, boot, network, service, application, in that order. A fault at a lower layer breaks everything above it.
  3. Read the evidence. LEDs, logs, error text. Copy errors exactly, since the first line of a Python traceback and the last are both useful.
  4. Change one thing at a time, and undo changes that did not help.
  5. Write down what fixed it for next time.
flowchart TD
    A["Symptom"] --> B{"Red power LED steady?"}
    B -- no --> C["Power supply, cable, board"]
    B -- yes --> D{"Green LED flickers at boot?"}
    D -- no --> E["SD card or boot files"]
    D -- yes --> F{"On the network?"}
    F -- no --> G["Network checklist"]
    F -- yes --> H{"Service or script failing?"}
    H -- yes --> I["Read the journal"]

Work from the bottom layer upward.

Power and boot

  • No lights: try another supply and a short cable, and reseat the card. Check the supply is the right rating for the model (Pi 4: 5 V 3 A; Pi 5: 5 V 5 A recommended).
  • Red LED on, green never flickers: the Pi cannot read the card. Reseat or reflash it; try another card.
  • Rainbow screen, then nothing: bad image or damaged card; reflash with Imager.
  • Lightning bolt icon or random reboots: under-voltage, see the temperature lesson and fix the supply.
  • Boots to emergency mode or a read-only filesystem: filesystem damage after a power cut; run fsck from another computer or reflash and restore from your backup.

Newer boards show boot errors on the green LED as blink patterns (for example, a fixed number of long and short flashes meaning "start4.elf not found"); the official documentation lists them by model.

Network problems

Work through them in order:

Terminal
ip -br addr                     # do we have an address?
ping -c 3 192.168.1.1           # can we reach the router?
ping -c 3 1.1.1.1               # can we reach the internet?
ping -c 3 example.com           # does DNS work?
rfkill list                     # Wi-Fi blocked? set country in raspi-config

SSH specific symptoms:

Message Likely cause
Connection refused SSH server not running or the wrong port
Connection timed out Pi is off, wrong IP, or a firewall drops packets
Permission denied (publickey) Key not authorised, or wrong permissions on ~/.ssh
Host key verification failed The Pi was reinstalled; remove the old line with ssh-keygen -R host
Name or service not known .local name not resolving; use the IP
Python Stand-in: a network diagnosis helper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Services and scripts

When a program works from the terminal but not as a service or cron job, the difference is almost always the environment: working directory, PATH, user, permissions. Look at the logs first:

Terminal
systemctl status weather
journalctl -u weather -n 50 --no-pager
journalctl -xe                          # recent errors with explanations
sudo -u weather /usr/bin/python3 /home/ana/weather/logger.py    # run as the service user

Common causes:

  • ModuleNotFoundError: the service uses system Python but you installed the library in a virtual environment. Point ExecStart at the venv's python.
  • PermissionError on /dev/...: the service user is missing a group (see users and permissions).
  • Exit code 203/EXEC: wrong path in ExecStart, or the script lacks execute permission.
  • Starts, then stops at once: the script finishes or raises; look at the first traceback in the journal.

GPIO and sensors

  • Nothing happens: wrong numbering (BCM versus physical pin), pin set as input, missing ground, a button wired without pull-up or pull-down.
  • I2C remote I/O error or the device is missing in i2cdetect -y 1: I2C disabled, swapped SDA and SCL, loose wire, wrong supply voltage, or a bad address.
  • Floating inputs that flip randomly: enable the internal pull-up or pull-down resistor.
  • Noisy analog readings: add a capacitor, average several samples, and keep sensor wires short.

Reading a Python error

Tracebacks are read from the bottom: the last line is the error, above it the call chain that led there.

Python Find the real error in a traceback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last line says what happened (KeyError: 22); the frames above say where. Fix the first frame in your own code, not in libraries.

Last resorts

  • Safe mode: remove the card, edit cmdline.txt or config.txt on another computer, undo your last change.
  • Reflash and restore: if you have a setup script and backups (backups lesson), a fresh card is often faster than debugging a mystery.
  • Ask well: include the Pi model, OS version (cat /etc/os-release), the exact error text, what you changed, and what you tried.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. The red LED is on but the green LED never flickers. What is the most likely cause?

    The green LED shows card activity; no activity means the boot media is not being read.
  2. 2. You can ping 1.1.1.1 but not example.com. Where do you look?

    Reaching an IP but not a name points at name resolution.
  3. 3. A service fails with ModuleNotFoundError but the script runs fine by hand. Likely fix?

    The service is using a different interpreter than your shell.
  4. 4. In a Python traceback, which line tells you what error occurred?

    The exception type and message are printed last.

Summary

  • Troubleshoot by layer: power, storage, boot, network, service, application.
  • Describe symptoms exactly and change one thing at a time.
  • LEDs, ip, ping, journalctl and i2cdetect are your main instruments.
  • Service failures are usually environment differences: path, user, Python, groups.
  • A setup script and backups make a reflash the universal fix.

Next: Practice Exercises and Project Ideas