Your Raspberry Pi fails to join Wi-Fi when the radio is off, the WLAN country is unset, a saved profile is stale, or the router is using a band your board does not support. Start with the fastest desktop checks, then move through Terminal fixes, headless setup, and recovery options. By the end, you will know whether the problem is a setting, a saved network profile, the router, or the Raspberry Pi OS install.
Start with the desktop Wi-Fi menu
Use the Raspberry Pi OS desktop first when you have a monitor and keyboard connected.
- 1.Select the wireless icon in the top-right system tray.
- 2.If Wi-Fi is off, select Turn On Wireless LAN.
- 3.Choose your wireless network from the menu.
- 4.Enter the Wi-Fi password when prompted, then select Connect.
- 5.If the menu says No APs found - scanning, wait a few seconds for NetworkManager to refresh.
- 6.For a hidden network, open Advanced Options, choose Connect to Hidden Wireless Network, enter the network name and security details, then select Connect.
Set the correct WLAN country
Open the Raspberry Pi menu in the top-left corner, followed by Preferences and Control Centre. Select the Localisation tab and choose Set WLAN Country.
Pick your country from the Country dropdown menu, then select OK and Close. On Raspberry Pi 3B+ onwards, Compute Module 4 onwards, and Raspberry Pi 400/500/500+, Wi-Fi depends on a set WLAN country.
Repair Wi-Fi from Terminal
Use this method on Raspberry Pi OS Lite, over SSH, or from the desktop Terminal. It also applies when the graphical Wi-Fi menu does not give you enough control.
Open Terminal and run sudo raspi-config. Select 5 Localisation options, then L4 WLAN Country. Choose the country that applies to you and confirm with OK. Confirm the next prompt with OK.
Run nmcli radio wifi. If it returns disabled, run nmcli radio wifi on. Next, run nmcli dev wifi list and find your network in the SSID column. Look for an asterisk in the IN-USE column to confirm the Pi is connected.
For a password-protected network, run sudo nmcli --ask dev wifi connect your_ssid. Enter the network password when prompted. For an open network, run sudo nmcli dev wifi connect your_ssid.
For a hidden network, run sudo nmcli --ask dev wifi connect your_ssid hidden yes. Enter the requested credentials when prompted.
Remove a bad saved Wi-Fi profile
The most common cause after a router password, security mode, static IP, or DNS change is an old NetworkManager profile being reused.
Open Terminal and run nmcli connection show. Find the saved Wi-Fi connection name that matches the network causing trouble.
Run sudo nmcli connection delete id "connection_name". Wrap the name in quotes, because saved profiles often contain spaces, such as Pi Towers or Wired connection 1. Do the same for an SSID that contains spaces.
Run sudo nmcli --ask dev wifi connect your_ssid and type the current Wi-Fi password carefully. If Secrets were required, but not provided appears, rerun the connect command and re-enter the password.
Preconfigure Wi-Fi for a headless Raspberry Pi
Install Raspberry Pi Imager from raspberrypi.com/software, or run sudo apt install rpi-imager on Raspberry Pi OS.
Open Raspberry Pi Imager, then open Device. Select your Raspberry Pi model and select Next. Open OS, choose an operating system, and select Next.
Open Storage and select your microSD card or storage device. Select Next, then open Customisation and the Wi-Fi subtab. Choose a secure network or an open network, then enter the SSID.
For a secure network, enter and confirm the password. If the network does not broadcast its name, enable Hidden SSID. Open the Localisation subtab and choose your capital city so Imager sets the time zone, keyboard layout, and Wi-Fi regulatory domain.
Continue to Writing and select Write. Confirm with I understand, erase and write. Do not use boot-folder wpa_supplicant.conf on current Raspberry Pi OS Bookworm or newer; use Imager customisation instead.
Recover access with Ethernet
This fixes a headless Pi that never received usable Wi-Fi credentials. Plug an Ethernet cable into the Raspberry Pi Ethernet port until it clicks, then connect the other end to a router port.
Use a USB Ethernet adapter for a model without an Ethernet port. Wait for Raspberry Pi OS to connect to the network automatically. Open Terminal and run sudo apt update.
Run sudo apt full-upgrade. Reboot after firmware or kernel updates, or when the system prompts you to restart.
Clear captive portals and proxy blocks
On hotel, school, library, and guest Wi-Fi, the Pi joins the network before internet access works. Run nmcli networking connectivity check to see whether NetworkManager reports none, portal, limited, full, or unknown.
When the state is portal, open Chromium or Firefox and complete the network sign-in page. Run the connectivity check again and confirm that it reports full.
On work, school, or restricted networks, proxy settings control internet access after Wi-Fi connects. In sudo raspi-config, open 6 Advanced Options, then A3 Network Proxy Settings, choose P1 All, P2 HTTP, P3 HTTPS, P4 FTP, or P5 Exceptions, enter the proxy details, finish with OK and Finish, then reboot.
Match the Wi-Fi band to your board
The most common hardware mismatch is a 2.4 GHz-only Raspberry Pi trying to join a 5 GHz-only SSID. Check your Raspberry Pi model's Wireless Connectivity in the hardware documentation.
Use a 2.4 GHz SSID for Raspberry Pi 3 Model B, Zero W, Zero WH, Zero 2 W, Zero 2 WH, Pico W, Pico WH, and Pico 2 W. Use 2.4 GHz or 5 GHz on Raspberry Pi 3B+, 3A+, 4B, 5, 400, 500, 500+, and wireless Compute Module variants. If the board has no built-in Wi-Fi, use Ethernet or a supported wireless USB stick.
Rebuild a tangled Raspberry Pi OS install
Use this method when Wi-Fi stays unreliable after old upgrades or repeated network changes. It is slower than deleting a saved profile, but it gives Raspberry Pi OS a clean network configuration.
Back up important files, then use Raspberry Pi Imager to write a new Raspberry Pi OS image to new boot media. Set Wi-Fi in Customisation before first boot, then set localisation in Customisation before first boot.
Use a clean install when moving between major Raspberry Pi OS releases, such as Bookworm to Trixie. Do not switch networking back to dhcpcd through raspi-config as a current fix. Use NetworkManager and nmcli on Raspberry Pi OS Bookworm and newer.
Frequently Asked Questions
Does Raspberry Pi OS support WPA3 Wi-Fi networks?
Yes. The current NetworkManager Wi-Fi steps cover WEP, WPA, WPA2, and WPA3 networks. Enterprise networks are outside the standard consumer setup path.
What does Secrets were required, but not provided mean?
It means the password you entered was not accepted. Raspberry Pi documents this error as an incorrect password. Run the nmcli connect command again and enter the Wi-Fi password carefully when prompted.
Can I fix headless Wi-Fi with wpa_supplicant.conf on Bookworm or Trixie?
No. Current Raspberry Pi OS Bookworm and newer do not use the old boot-folder wpa_supplicant.conf setup. Use Raspberry Pi Imager customisation before first boot.
Should I disable WLAN power saving to fix unstable Wi-Fi?
Use raspi-config's WLAN Power Save option only when Raspberry Pi support instructs you to change it. It is an advanced setting, not a general first fix.