Skip to content

Raspberry Pi Headless Setup Troubleshooter

Select the first symptom you can prove. This browser-only tool returns a short diagnostic path for Raspberry Pi OS Trixie without scanning your network, uploading addresses, or storing answers. Run commands only on devices and networks you administer.

The tool cannot inspect the Raspberry Pi or execute a command. It deliberately starts with observable evidence, avoids guessing an address, username, or Wi-Fi state, and leaves every placeholder visible for you to review.

Before troubleshooting

Keep these facts available:

  • Raspberry Pi model and power-supply rating
  • exact Raspberry Pi OS image and write date
  • connection method and cable type
  • hostname and username configured in Raspberry Pi Imager
  • whether SSH was enabled and which public key was selected
  • router DHCP lease list, if you administer the router
  • a display and keyboard, or a known-good recovery image

Do not assume the username is pi. Current Raspberry Pi OS images require you to create a user in Imager or during first boot.

Symptom matrix

Evidence Check first Avoid
No activity indication Image, storage, power, boot diagnostics Rewriting network files before proving boot
No DHCP lease Ethernet link or Imager Wi-Fi settings Randomly scanning networks you do not own
IP works, .local fails Client mDNS support Reconfiguring SSH
SSH timeout Address, route, VLAN, port filtering Repeated password/key changes
Connection refused SSH service/listening socket Deleting client keys
Permission denied (publickey) Username, offered key, server file permissions Enabling password login before recovery is tested
Host key changed Device identity and re-imaging history Blindly deleting the warning
USB interface absent Data cable, correct USB port, Gadget configuration Assuming every Pi model supports the same mode

Safe discovery order

  1. Confirm the system booted.
  2. Check the router's DHCP leases or known network inventory.
  3. Test the configured hostname.
  4. Test the known IP address.
  5. Use verbose SSH output only after confirming the endpoint.

From a client you administer:

1
2
ping -c 3 <hostname>.local
ssh -vv <username>@<known-ip>

ping can be blocked even when SSH works, so it is supporting evidence rather than a final verdict. Do not publish verbose SSH logs without removing usernames, addresses, key fingerprints, and network details.

Recover locally when remote evidence stops

Connect a display and keyboard, then inspect:

1
2
3
4
5
6
7
8
cat /etc/os-release
hostnamectl
ip -brief link
ip -brief address
nmcli device status
systemctl status ssh --no-pager
ss -ltnp | grep ':22'
journalctl -u ssh -b --no-pager | tail -50

Wi-Fi first-boot checks

Raspberry Pi OS Trixie uses NetworkManager. Configure the country, SSID, password, hostname, user, and SSH through Raspberry Pi Imager before writing the card. Old tutorials that drop wpa_supplicant.conf onto bootfs do not describe the current supported first-boot path.

Locally, inspect the connection without printing its secrets:

1
2
3
4
nmcli device status
nmcli connection show
nmcli --fields IN-USE,SSID,SIGNAL,SECURITY device wifi list
rfkill list

Use sudo nmcli --ask device wifi connect "<SSID>" if you must reconnect interactively; --ask avoids placing the password directly in shell history.

SSH key checks

On the client:

1
2
3
ssh -G <username>@<known-ip> | grep -E '^(user|hostname|identityfile) '
ssh-add -L
ssh -vv <username>@<known-ip>

On the Raspberry Pi console:

1
2
3
4
getent passwd <username>
namei -l /home/<username>/.ssh/authorized_keys
sudo sshd -t
sudo journalctl -u ssh -b --no-pager | tail -50

The .ssh directory normally needs mode 700 and authorized_keys mode 600, owned by the target user. Fix only the intended account after verifying the path:

1
2
3
sudo chown -R <username>:<username> /home/<username>/.ssh
sudo chmod 700 /home/<username>/.ssh
sudo chmod 600 /home/<username>/.ssh/authorized_keys

Keep a working console or second SSH session open before changing authentication policy.

Host-key warnings require identity verification

A changed host key can be expected after re-imaging, but it can also indicate that an address now belongs to another device or that a connection is being intercepted. Compare the fingerprint on the Raspberry Pi console:

1
sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Only after confirming the device and fingerprint should you remove the old client entry:

1
ssh-keygen -R <verified-host-or-ip>

Reconnect and compare the newly presented fingerprint before accepting it.

FAQ

What is the default Raspberry Pi username and password?

There is no universal default account on a current fresh Raspberry Pi OS installation. Use the username created in Raspberry Pi Imager or the first-boot wizard.

Should I create an empty ssh file?

Raspberry Pi Imager's OS customisation is the preferred current method because it configures the user and authentication method together. An empty ssh file alone does not create a user or install your key.

Why does .local fail when the address works?

.local depends on multicast DNS support and local-network policy. Use the known DHCP address while correcting mDNS on the client; do not rebuild a working SSH server.

Does a timeout mean the password is wrong?

No. A timeout happens before authentication completes. Check boot, address, routing, VLAN/firewall policy, and whether TCP port 22 is reachable.

Can this tool scan my network?

No. It runs locally in the page and produces diagnostic commands only. Use the router's authorised DHCP inventory instead of broad discovery scans.