Just got your new Pi and excited to get it setup for Octoprint on your 3D printer rig, Kodi for binge streaming, RetroPie for old skool gaming, Kali for l33t haxx0rzing? Can't wait to toss on those cool looking heat sinks that came with the kit so you can overclock the Pi and pwn the crypto scene? Or that neat HAT/Bonnet add on board you also bought?

WAIT! STOP! DON'T!

These options are great, but have potential hiccups to get going due to their complexity. If you jump straight to one of these configurations and run into issues with the Pi "not booting", the troubleshooting becomes extremely troublesome. Is it the OS? Did something get shorted by touching the GPIO pins? Is the HAT/Bonnet configured correctly? Or is it the Pi itself? Unknown.

Even if you've configured a million Pi's in a similar way before - DO THIS FIRST:

Get the Raspberry Pi OS from the Raspberry Pi website:

and follow their instructions for installing the OS image to an SD card. Once done, insert the SD card in the Pi, apply power, and let it boot. The non-Desktop Lite version works fine for this check.

Headless Configuration

Pretty much every current model Pi includes WiFi. Therefore, it's fairly easy to configure the Pi to connect to your local network. You can then try pinging the Pi or SSHing in to see if it booted correctly.

The necessary configuration can be done using rpi-imager:

so that the resulting SD card image will be ready to go.

Attaching a Monitor

If you're not super familiar with "pinging" or "SSHing" into the Pi, then you'll probably want to attach a monitor to the Pi's HDMI output. This should be fine, but can introduce potential issues. HDMI cables can be bad. HDMI adapters can be bad. EDIDs (identification handshaking between the Pi and the monitor) may get wrapped around the axle. Digital Rights Management (DRM) stuff can introduce many other unknowns. So as simple as this should be, it is not super robust.

Go ahead and try attaching a monitor if it's the only option you're familiar with. One suggested change that seems to help in a lot of cases is to enable safe mode on the HDMI output. To do so, edit /boot/config.txt and find these lines:

To uncomment and enable the feature, remove the # from the second line so it looks like:

This won't be super awesome 4k 120FPS HDMI, but we don't care. We just want to see something usable.

Power Supply

This should be simple, but even just getting power to the board can be an issue. In theory, should be able to use a 5V supply with enough current for whatever model Pi you're using, like 3 amps for a Pi 4, etc. But make sure you're using a USB cable that can actually deliver the necessary current (3 amps is a fair amount of juice).

Specific to the Pi 4, early models had a known issue with the USB-C port that would make some power supplies just give up. So make sure to use a known good power supply, like this one:

Did It Work?

How do you know if it worked? All we are looking for is a basic bootup. If you can ping the Pi or get to a basic login prompt, that is good enough. For the headless setup, try SSHing in. If a monitor is attached, just seeing a boot screen is enough.

You now know the basic Pi board hardware itself is nominally OK. You can now move on to whatever specific project you have planned for the Pi. Keeping all the other considerations outlined in this guide in mind as you proceed.

Did It NOT Work?

If the Pi still appears to "not boot" or "not work" for some reason, even after doing the above setup, then please post the issue in the Adafruit forums:

Provide as many details as possible about what is happening. Simply saying "it won't boot" or "it doesn't work" does not provide useful information for troubleshooting. Providing a photo of the setup is also helpful.