Troubleshoot Your Pwnagotchi

Troubleshoot Your Pwnagotchi

Pwnagotchi Not Loading? Here’s How to Troubleshoot It

So you’ve flashed the SD card, connected your screen, powered up, and... nothing. Your adorable little AI Wi-Fi parasite isn’t waking up. No face. No blinking. Just dead silence. Don’t worry—we’re going to get your Pwnagotchi back to life.

Here’s a full troubleshooting guide when your Pwnagotchi won’t boot or load properly:

 1. Check Your Power Supply

It seems obvious, but an underpowered Pi is the #1 issue. Make sure you’re using a 5V/2.5A power supply (or better). Avoid cheap battery banks—they sag under load, especially with displays.

Tip: Try powering via the data port instead of the power port during testing. Some setups only trigger boot when powered from the USB port wired for data.

 2. Confirm You Flashed the Right Image

Make sure you're using a proper tool like Raspberry Pi Imager or Balena Etcher and that you're flashing the correct .img from the Pwnagotchi GitHub.

After flashing, the SD card should mount a boot partition you can access on any OS. If you don’t see files like kernel7.img or cmdline.txt, something went wrong.

📝 3. Validate Your config.toml File

This is a major failure point. TOML is strict. A single misplaced quote or comma will silently fail the config load.

✔ Use https://www.toml-lint.com to validate your config before booting.

4. Check for LED Activity

Even with no display, your Pi might be alive. Watch the onboard LEDs:

  • Solid red, no green: Bad SD or no bootloader

  • Green blinking: It’s reading the SD and trying to boot

5. Try to SSH In

If your unit’s not displaying a face, try connecting over USB:

  1. Plug into the data port of your Pi (not the power port)

  2. Set your PC’s IP to 10.0.0.1, netmask 255.255.255.0

  3. Run:

    bash
    ssh pi@10.0.0.2 # default password: raspberry

If this works, your Pwnagotchi is alive! You can now check logs, update config, or force a reboot.

6. First Boot Takes Time — Be Patient

If it’s your first boot ever, don’t touch anything for 5–10 minutes. The Pi is generating RSA keys and doing initialization. If you unplug too early, it might corrupt the image.

7. Re-seat or Test Your Display

Many issues come from loose screens or incorrect config. Check:

  • Display type matches: waveshare_4, inky, etc.

  • Refresh rate is set to 0 for e-ink (ui.fps = 0)

  • GPIO header is seated all the way down

Still blank? Boot without the screen and SSH in to test.

8. READ THE LOGS — THEY WILL SAVE YOU

If you can SSH in but things aren’t working right (blank screen, no BT tethering, plugins failing), the log file is gold.

Start Pwnagotchi in debug mode via SSH:

sudo systemctl stop pwnagotchi
sudo pwnagotchi --debug

In another terminal:

tail -f /var/log/pwnagotchi.log

Look for:

  • Display init errors

  • Config parsing issues

  • Plugin failures

Do not skip this. 99% of issues are revealed in the log. If you're asking for help online and you haven't checked logs, you're troubleshooting blind.

9. Restore a Clean Image

If things are a total mess, start fresh:

  1. Flash the image again

  2. Place a fresh, valid config.toml in the boot partition

  3. Boot with patience

  4. SSH in and manually restore backups or handshakes

Final Notes

  • Use a high-endurance SD card (SanDisk Ultra/Extreme)

  • Always shut down properly via SSH or the web UI

  • Back up your config and handshakes regularly

  • Don’t ignore the logs — they are your window into your Pwnagotchi’s soul

Need a fully assembled Pwnagotchi, screen kit, or just a killer case?
Check out BiscuitShop.us 👾

Happy pwning!

Back to blog