Docs

Troubleshooting


DevGuide

Troubleshooting Topics

Powerup Issues

Observe the LEDs on the Raspberry Pi during startup

The red power LED (labelled PWR) must be solid on (the Raspberry Pi has a low power detection circuit that will turn off this LED if the power drops below a fixed threshold, i.e., it has a "brownout" detector). If this LED is off, nothing will work properly. Ensure you have a sufficient power supply (5V 2A is recommended, with 1A as a bare minimum even without USB devices attached consuming power).

The green activity LED (labelled ACT) must flash during boot. This LED indicates activity at the MicroSD flash card. Since the lowest level bootloader must be read from this flash device, nothing will function properly unless this LED flashes during boot. No output will be seen on the console screen until after the bootloader has been read from flash and run.

Wired Network Connectivity

Assuming you are using the wired Ethernet connection configured in the standard way using DHCP, your device should attach itself to your local area network upon boot and have an IP address assigned to it.

You can verify your network address with the sudo ifconfig command (or /sbin/ifconfig) on the console which will show all of the active physical and virtual network interfaces on your device. For example, a wired ethernet network interface like "eth0" should appear similar to the following:

eth0      Link encap:Ethernet  HWaddr b8:27:eb:0d:99:63  
          inet addr:192.168.123.107  Bcast:192.168.123.255  Mask:255.255.255.0
          inet6 addr: fe80::ba27:ebff:fe0d:9963/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:582239 errors:0 dropped:500 overruns:0 frame:0
          TX packets:381086 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:385243295 (367.3 MiB)  TX bytes:200840694 (191.5 MiB)

The IPv4 address assigned to an interface is shown in the inet addr section (e.g., in the example above, this device's local area network address is 192.168.123.107).

If you do not have an address on your wired network interface check your cables, switches, and DHCP server (most likely your router).

If you have an address assigned, you can verify your connectivity by using the ping utility. A good place to start is with a well-known domain name, like "google.com". If you see results similar to what is shown below then your device is connected to the internet and domain name resolution is also configured correctly, then you do not have a networking problem.

pi@horizon-0000000123456789:~$ ping -c 3 google.com
PING google.com (216.58.192.46) 56(84) bytes of data.
64 bytes from nuq04s30-in-f46.1e100.net (216.58.192.46): icmp_seq=1 ttl=55 time=18.0 ms
64 bytes from nuq04s30-in-f46.1e100.net (216.58.192.46): icmp_seq=2 ttl=55 time=9.74 ms
64 bytes from nuq04s30-in-f46.1e100.net (216.58.192.46): icmp_seq=3 ttl=55 time=11.8 ms

--- google.com ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2003ms
rtt min/avg/max/mdev = 9.740/13.191/18.009/3.511 ms
pi@horizon-0000000123456789:~$ 

If that ping fails, try to ping the IP address of your local gateway device. The address of your gateway is the internal address you provided, or it chose by default, when you configured your router. If you don't know your gateway address, you can use any other computer attached to your network to get it. Just check the network settings screen on that other device. In a typical household /24 subnet, the gateway address is usually the .1 or .254 address (i.e., the first or last address) in that network. For example, if your device's IP address is 192.168.123.100, then your gateway is likely 192.168.123.1, or 192.168.123.254. If you are unable to ping your gateway, then you likely have a local network configuration problem on the Raspberry Pi, or a physical network wiring problem.  You will need to debug the issue with whomever maintains the local area network where the device is connected.

If the google.com ping fails, but you are able to ping your gateway, this may imply a domain name resolution issue.  Try to ping a well-known IP address (i.e., not a domain name) outside of your local area network.  If you use an actual numeric IP address then the domain name resolution service will not be involved. For example, try to ping the well-known Google server at 8.8.8.8:

pi@horizon-0000000123456789:~$ ping -c 3 8.8.8.8
PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_seq=1 ttl=55 time=21.0 ms
64 bytes from 8.8.8.8: icmp_seq=2 ttl=55 time=11.4 ms
64 bytes from 8.8.8.8: icmp_seq=3 ttl=55 time=11.0 ms

--- 8.8.8.8 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2002ms
rtt min/avg/max/mdev = 11.009/14.531/21.089/4.643 ms
pi@horizon-0000000123456789:~$ 

If you are able to ping numeric IP addresses like your gateway, and 8.8.8.8, but the "google.com" domain name cannot be resolved, then your DNS configuration on the Raspberry Pi is suspect.  This DNS information is provided by your DHCP server (router), please check its settings.

Wireless Network Connectivity

If you are using a wireless network, you can check your network configuration using the steps shown above for wired network connectivity. For example, the sudo ifconfig command (or /sbin/ifconfig) should show something similar to the following for your wireless interface:

wlan0     Link encap:Ethernet  HWaddr 74:da:38:66:1a:61  
          inet addr:192.168.123.98  Bcast:192.168.123.255  Mask:255.255.255.0
          inet6 addr: fe80::76da:38ff:fe66:1a61/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:760940 errors:0 dropped:12587 overruns:0 frame:0
          TX packets:101311 errors:0 dropped:1 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:174866970 (166.7 MiB)  TX bytes:41621707 (39.6 MiB)

If you do not have an address in the inet addr section, then verify that your Raspberry Pi has actually associated to your WiFi access point by going to the Raspberry Pi console and running the similar command, sudo iwconfig. You should see output similar to the following for your wireless interface:

wlan0     IEEE 802.11bgn  ESSID:"********"  Nickname:"<WIFI@REALTEK>"
          Mode:Managed  Frequency:2.452 GHz  Access Point: C4:04:15:19:F6:15   
          Bit Rate:72.2 Mb/s   Sensitivity:0/0  
          Retry:off   RTS thr:off   Fragment thr:off
          Encryption key:****-****-****-****-****-****-****-****   Security mode:open
          Power Management:off
          Link Quality=99/100  Signal level=71/100  Noise level=0/100
          Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
          Tx excessive retries:0  Invalid misc:0   Missed beacon:0

The ESSID section should show your wireless access point's SSID. If instead you see Not Associated, then your  configuration is incorrect and your device has not associated to your WiFi access point. You will need to correct your WiFi access credentials and reboot.

If your WiFi interface is associated, and you have an IP address, then you can debug any remaining network connectivity using the instructions given above for wired networks.

Note Regarding WiFi Power Management Features

USB WiFi dongles often have power-saving features that shut off the WiFi device when it appears to be idle. This can result in SSH sessions being terminated and other undesirable behaviors. One or both of the following approaches can be used to disable power-saving mode for your WiFi device:

Use sudo to edit the wlan0 section of your /etc/network/interfaces configuration file to add the line, "wireless-power off". For example, that part of my config looks like this:

auto wlan0
allow-hotplug wlan0
iface wlan0 inet manual
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
wireless-power off

Reconfigure the kernel driver module for the WiFi chip.

If you have a Pi 2 and are using the recommended WiFi dongle (or another one using the same chips), you can use sudo to edit /etc/modprobe.d/8192cu.conf (creating the file if it does not exist) and add the line below to disable power saving mode on that device:

options 8192cu rtw_power_mgnt=0 rtw_enusbss=0

Network Reliability

If your network connection appears to be unreliable, you should verify that you have a sufficient power supply for your device (a 5V 2A supply is recommended, but 1A may be sufficient if you are using wired Ethernet).

If your network is unreliable and you are using wireless connectivity, you may be suffering from an overactive power-saving feature on your WiFi device. See the wireless network connectivity section above for information about how to disable this feature.