Skip to content

Raspberry Pi NetworkManager: nmcli Setup and Troubleshooting

First identify whether the problem is the connection, address, route, name lookup or SSH service. Raspberry Pi OS Bookworm and Trixie normally use NetworkManager; copying older dhcpcd.conf instructions into that setup can create conflicting configuration.

Before you start

You need a local Pi terminal or an established SSH login and the terminal lesson. Commands below run on the Pi unless marked client computer.

Start with read-only checks. Changes to the active network can cut off SSH, so use a local console or verified alternate connection before changing the link you depend on. A profile name and an interface name are not the same thing.

See the official Raspberry Pi configuration reference and nmcli manual for the supported tools.

Start with your symptom

Outcome: identify the failing layer before changing anything, then check the intended connection and a fresh SSH login after one targeted repair. If you cannot log in at all, start with the headless connection troubleshooter.

If nmcli is missing or NetworkManager is not running

Run these read-only checks on the Pi before trying to change a connection:

1
2
3
4
cat /etc/os-release
command -v nmcli
systemctl is-active NetworkManager
systemctl status NetworkManager --no-pager

If command -v prints no path, the command is unavailable in your current environment; check the OS and installed networking stack before installing anything. If is-active reports inactive or failed, the service is not currently active; inspect the status and logs for the actual reason. A status check may return a nonzero exit code when a service is not running. Some older or customized systems use another network manager, so a missing command or inactive service does not by itself prove a broken network.

Do not start, restart, enable, remove or replace network services as a generic first fix over your only SSH connection. Keep a local console or a separately verified recovery path and identify the existing manager first. If the problem is an APT error involving network-manager, see the update-repair guide rather than treating it as a Wi-Fi password problem.

1. Identify interfaces and profiles

1
2
3
4
5
nmcli general status
nmcli device status
nmcli -f NAME,UUID,TYPE,DEVICE connection show --active
ip -brief address
ip route

An interface, such as wlan0 or eth0, is a network device. A profile, such as a Wi-Fi network name or Wired connection 1, contains saved connection settings. Your device/profile names may differ.

Check: the interface used for your connection shows connected and has the expected address. Disconnected unused interfaces are normal. lo is the loopback interface, not the connection to your router.

The route table normally has a default via entry for the internet gateway. An address alone does not prove DNS or internet access. NetworkManager's overall connectivity assessment is also not a substitute for testing your intended destination.

Read an address and route

Illustrative IPv4 output, not values to copy into your Pi:

1
2
3
4
5
6
$ ip -brief address
lo       UNKNOWN  127.0.0.1/8 ::1/128
wlan0    UP       192.168.10.42/24
$ ip route
default via 192.168.10.1 dev wlan0 proto dhcp metric 600
192.168.10.0/24 dev wlan0 proto kernel scope link src 192.168.10.42 metric 600

Here 192.168.10.42 belongs to the Pi, /24 describes its local subnet, and 192.168.10.1 is the gateway. The local-subnet route does not replace a default route to other networks. UNKNOWN on lo is not a Wi-Fi fault. An IPv4 address in 169.254.0.0/16 alone is not evidence of a router DHCP lease; IPv6-only networks also need their own route checks.

With Ethernet, Wi-Fi or a VPN active together, several routes can be legitimate. Ask the kernel which IPv4 path it would use:

ip route get 1.1.1.1

Look for dev (outgoing interface), src (source address), and via when a gateway is needed. This route lookup does not send a ping or prove that the destination answers. Use the actual destination IP when diagnosing another service. Do not delete routes just because there are two defaults; policy rules, more-specific routes and VPNs can affect selection. For an IPv6 destination, use ip -6 route get with its actual IPv6 address instead.

2. Understand what DHCP supplies

A normal home router supplies an address, prefix, gateway and DNS servers through DHCP. You usually do not need a static IP for initial setup.

Use the actual connected interface in place of wlan0:

nmcli -f GENERAL,IP4,IP6 device show wlan0

Check: find its connection name, address, gateway and DNS entries. Do not share complete output without considering hostnames, MAC addresses and public addresses.

If Ethernet is available, connect a cable to a LAN port on the router and inspect the device state. Do not plug it into a router's WAN port or assume a cable to an unconfigured client computer supplies DHCP.

Read the device state before reconnecting

Replace wlan0 with the interface from step 1. These commands inspect state and recent logs; they do not reconnect the device:

1
2
3
nmcli radio wifi
nmcli -f GENERAL.STATE,GENERAL.REASON,GENERAL.CONNECTION device show wlan0
journalctl -b -u NetworkManager -n 50 --no-pager
  • disconnected: NetworkManager has no active connection on that device. Inspect the radio, intended SSID and profile; use the intentional Wi-Fi connection step only if needed. A disconnected spare Ethernet port is normal.
  • unavailable: inspect the reason and log. A disabled or blocked radio, missing driver/firmware or absent hardware needs a different response from a wrong password. A globally enabled Wi-Fi radio does not rule out a hardware block.
  • unmanaged: NetworkManager is not managing this device. Check whether another service or deliberate device rule owns it before changing that policy. Do not apply managed yes to every interface, especially bridges, containers and USB links.
  • connecting or repeated activation failures: match the reason/log to authentication, association or address configuration. A request for credentials differs from a DHCP timeout. Fix the reported stage rather than repeatedly restarting the service.
  • connected: continue with the address, selected route and DNS checks. Connection state alone is not proof of internet access.

The log may omit older events or require additional log-reading permission. Review SSIDs, addresses and other private details before sharing it; do not collect saved passwords with --show-secrets.

3. Connect to Wi-Fi intentionally

Perform this from a local console or alternate connection if changing Wi-Fi could interrupt SSH. It changes the radio/profile state; skip it if your current connection already works.

1
2
3
nmcli radio wifi on
nmcli device wifi list
sudo nmcli --ask device wifi connect "YOUR-SSID"

Replace YOUR-SSID with the exact network name. --ask prompts for the secret rather than putting the password directly into shell history. Match the correct access point and regulatory country; set the country in Imager or raspi-config.

For a hidden network, use the same command with hidden yes. Do not interpret an absent 5 GHz network as a password error when your board only supports 2.4 GHz.

Then repeat the observations from steps 1 and 2. Success: the intended profile is active, the device has an address, and a new SSH login works from the client if remote access is required.

If the credentials are wrong, correct them using the supported interactive interface or reconnect with --ask. Do not delete every saved profile or restart NetworkManager as the first repair.

DNS diagnostics

Run on the Pi:

1
2
3
nmcli -f IP4.DNS,IP6.DNS device show wlan0
getent ahosts raspberrypi.com
ls -l /etc/resolv.conf

Use your actual interface name. getent uses the system's name-service configuration, which is useful for testing what applications can resolve.

Interpret the result: address rows mean this hostname resolved through the system's name-service path; STREAM and DGRAM rows describe socket types, not duplicate DNS failures. No rows or a lookup error means resolution did not return a usable result. Repeat with the hostname from the failing application or APT error, not its full https://... URL. One working hostname does not prove every domain works.

If only name lookup fails, inspect the active profile's DNS entries and /etc/resolv.conf target. If those point to your router or Pi-hole, check that resolver's availability before changing the Pi. If names resolve but HTTPS fails, check the application's actual error, clock, certificate and endpoint instead of replacing DNS servers. The getent reference explains the system lookup path; it is not a direct query to a particular DNS server.

resolvectl is appropriate only when systemd-resolved is installed and active. It was absent on the available Pi 4B despite working DNS, so this course does not require it or recommend installing it as a generic repair.

To test the path independently of names, inspect ip route and substitute its actual gateway address below:

ping -c 3 192.168.1.1
ping -c 3 1.1.1.1

These send traffic; they do not modify configuration. Lack of a ping reply is not conclusive because ICMP may be filtered. Conversely, a successful ping does not prove HTTPS, package repositories or authentication work.

Observation Investigate next
No link/connected interface Cable, Wi-Fi credentials, radio, country
Connected but no expected address DHCP and profile settings
Local gateway reachable but internet path fails Upstream router, route or network policy
Public IP reachable but name lookup fails Resolver configuration and DNS server reachability
DNS works but one application fails Its endpoint, protocol, certificate/time or service

Do not overwrite /etc/resolv.conf as a persistent fix; the active networking stack may manage it.

4. Separate SSH from network connectivity

On the Pi, inspect the service:

1
2
3
systemctl is-active ssh
systemctl is-enabled ssh
ss -lnt

On the client computer, use the account you created and the hostname or actual router-assigned IP:

ssh your-user@pi-setup.local

If the IP works but .local does not, investigate client-side mDNS/network discovery rather than rebuilding the OS. If SSH says Connection refused, check that the address is your Pi and its service is listening. A timeout, denied password and changed host key are different failures.

Keep the original session open while testing a second one. For enabling SSH, use the settings lesson. Never disable host-key checks or expose port 22 on the router merely to make a LAN exercise work.

5. Optional: plan a stable address

Prefer a DHCP reservation on your router when you control it. This keeps address allocation in one place and avoids an accidental duplicate.

A device-side static profile requires a network plan: reserved address, prefix, gateway and DNS. Do not copy the example values into an unrelated network.

From a local console, record the known-good profile and create a separate test profile:

1
2
3
4
5
6
7
8
nmcli connection show "Wired connection 1"
sudo nmcli connection clone "Wired connection 1" "Pi wired test"
sudo nmcli connection modify "Pi wired test" connection.autoconnect no
sudo nmcli connection modify "Pi wired test" \
  ipv4.method manual \
  ipv4.addresses "192.168.10.50/24" \
  ipv4.gateway "192.168.10.1" \
  ipv4.dns "192.168.10.1"

These names and values are examples. The clone is kept from autoconnecting before you test it. Changing a saved profile does not prove that it is active.

Only with a confirmed recovery route, activate the intended profile:

sudo nmcli connection up "Pi wired test"

Repeat address, route, DNS and second-login checks. If it fails, use the local console to reactivate the original profile:

sudo nmcli connection up "Wired connection 1"

If everything is correct and persistence is required, decide explicitly whether to enable autoconnect and how competing profiles should be prioritised. Do not leave multiple conflicting auto-start profiles without testing reboot behaviour.

Advanced NetworkManager releases provide checkpoints for rollback, but verify support and recovery on the installed version before relying on that feature. This lesson does not perform a remote static-address change.

When a NetworkManager update fails

An APT error naming network-manager is not necessarily a Wi-Fi problem. Record the exact error, check available disk space and repository configuration, then distinguish network failures from interrupted package operations.

Do not remove NetworkManager from a remotely administered Pi or mix Bookworm/Trixie repositories to force installation. Use the dedicated update-repair guide. Routine package upgrades and major OS migrations are separate tasks.

Troubleshooting

Recover without making a second problem

Before an intentional change, record the known-good profile's UUID from step 1 and retain console or alternate access. If the changed profile cuts off SSH, use that recovery access to reactivate the original profile with sudo nmcli connection up uuid "YOUR-RECORDED-UUID". Replace the placeholder with the UUID you recorded; this changes the active connection and cannot be run through a dead SSH session. Reactivating a profile does not undo edits to that same profile, which is why the static-address exercise uses a separate clone.

Make one change, then repeat device/address, route, intended-host lookup and second-login checks. If the original connection works, do not also change DNS, firewall and SSH policy. If you need help, share the failing stage, exact error, OS release and redacted output, not passwords or an entire unrestricted log dump.

Checkpoint: if Wi-Fi is connected and a hostname resolves, but SSH says Connection refused, which service would you inspect? Why does a successful ip route get not prove internet access?

Next steps

Next, learn Users and Permissions. Optional networking projects belong after the foundations:

Want to write a program that uses the connection? With basic C++ and a working compiler, continue to addresses, ports and sockets, then your first UDP exchange. These are programming lessons, not additional Wi-Fi configuration steps; the first exchange stays on one Pi using loopback.

To understand why a working network can still return a partial application message or close a connection, continue later to your first TCP connection. Follow that course's development prerequisites first; no further router or Wi-Fi changes are required for its loopback examples.

Diagnostic references reviewed on 3 November 2026.

Donate