Diagnose and Tune NetworkManager-wait-online Delays

You will finish with a measured explanation for a slow NetworkManager-wait-online.service, rather than simply masking the delay with a shorter timeout. The examples use NetworkManager 1.46.0 from Ubuntu package network-manager 1.46.0-1ubuntu2.8 and systemd's installed unit.

Allow about fifteen minutes. You need a shell and permission to read service status and logs. The investigation is read-only. The optional timeout change near the end needs sudo and affects later boots, so treat it as a configuration change, not as a diagnostic shortcut.

1. Confirm what the service waits for

Read the unit actually installed on the machine:

$ systemctl cat NetworkManager-wait-online.service
# /usr/lib/systemd/system/NetworkManager-wait-online.service
[Service]
Type=oneshot
ExecStart=/usr/bin/nm-online -s -q
RemainAfterExit=yes
Environment=NM_ONLINE_TIMEOUT=60

The exact comments and unit path can vary. The important facts here are Type=oneshot, the nm-online -s -q command, and the 60-second NM_ONLINE_TIMEOUT value. The -s option waits for NetworkManager startup to settle. It does not mean that every interface must have a working route at the instant the command returns.

Checkpoint: record the effective state without changing it:

$ systemctl show NetworkManager-wait-online.service \
    -p ActiveState -p SubState -p Result -p ExecMainStatus -p TimeoutStartUSec
ActiveState=active
SubState=exited
Result=success
ExecMainStatus=0
TimeoutStartUSec=infinity

active (exited) is normal for this oneshot service. The service has completed its wait and remains recorded as active for dependency ordering.

2. Measure the wait outside a boot

Run the same helper in quiet startup mode and measure it with the shell. This asks NetworkManager for its current startup state; it does not restart networking:

$ time nm-online --wait-for-startup --quiet

real    0m0.0s
user    0m0.0s
sys     0m0.0s

A machine that has already completed startup normally returns immediately. On a host still waiting for a device, profile or dispatcher action, the command can take longer. The timing is host-specific, so do not treat the numbers above as a promised default.

For a direct result check, run:

$ nm-online --wait-for-startup --quiet
$ printf 'nm-online status: %s\n' "$?"
nm-online status: 0

Status 0 means that startup completed. A non-zero result means the wait did not succeed; keep that result with the service logs before changing anything.

3. Identify the connection that is holding startup open

List device and connection state as an ordinary user:

$ nmcli device status
DEVICE  TYPE      STATE      CONNECTION
enp1s0  ethernet  connected  Wired connection 1
wlan0   wifi      disconnected  --
lo      loopback  unmanaged   --

Your interface names and states will differ. Look for a device stuck in connecting, a profile that repeatedly fails, or an auto-connecting Wi-Fi profile on a machine that is not near its access point. A disconnected device is not automatically a fault: NetworkManager can reach startup complete once every relevant profile and device is in a conclusive state.

Inspect profiles without printing secrets:

$ nmcli -f NAME,UUID,TYPE,AUTOCONNECT connection show
NAME                 UUID                                  TYPE      AUTOCONNECT
Wired connection 1   11111111-2222-3333-4444-555555555555  ethernet  yes

Do not copy a UUID from this example. Use the exact name or UUID from your own output when you inspect a profile. If activation keeps retrying, check its logs and settings rather than disabling the wait service.

4. Read the boot and NetworkManager evidence

Ask systemd how long the unit took and show messages from the current boot:

$ systemd-analyze blame | grep NetworkManager-wait-online
  1.842s NetworkManager-wait-online.service
$ journalctl -b -u NetworkManager-wait-online.service --no-pager
$ journalctl -b -u NetworkManager.service --no-pager

The duration is specific to this boot. In the NetworkManager log, look for a profile that remains activating, repeated DHCP or IPv6 attempts, a missing bridge or bond port, a delayed pre-up dispatcher script, or a device waiting to appear. Wi-Fi also waits for an initial scan. Ethernet can wait for carrier, which makes an unplugged cable relevant.

Do not infer a healthy network from a successful wait. This service reports that NetworkManager's startup work reached a conclusion. It is a boot ordering gate for units using network-online.target, not a continuous connectivity monitor.

5. Fix the cause in the profile or device configuration

Prefer fixing the profile that is slow or impossible to activate. Examples include correcting a bridge or bond whose ports do not auto-activate, removing an obsolete auto-connect profile, or correcting DHCP, IPv4 and IPv6 requirements. Make one change at a time and capture the previous setting first.

Settings such as ipv4.may-fail, ipv6.may-fail, DHCP and router-advertisement timeouts, connection.wait-device-timeout, and connection.wait-activation-delay can change when startup is considered complete. They have different operational meanings. Do not set them merely to make boot look faster, especially on a host that needs a particular address family or interface before mounting remote storage.

Any nmcli connection modify command changes persistent profile state and can disrupt a live connection. Take a backup or write down the original value, use a maintenance window for production systems, and verify the profile after the change. If a change breaks activation, restore the original property value and reactivate the profile using your normal network change procedure.

6. Change only the service timeout when you have a reason

If the network is expected to take longer than the installed 60 seconds, override the service environment with a systemd drop-in. This does not repair activation; it only allows the wait to continue for longer:

$ sudo systemctl edit NetworkManager-wait-online.service

Add this drop-in in the editor, choosing a value appropriate to the host:

[Service]
Environment=NM_ONLINE_TIMEOUT=120

Save and close the editor, then verify the effective configuration:

$ systemctl cat NetworkManager-wait-online.service
$ systemctl show NetworkManager-wait-online.service -p Environment
Environment=NM_ONLINE_TIMEOUT=120

Apply the new value on a future service start or reboot according to your maintenance plan. If you need to undo this drop-in, remove all local overrides for this unit and verify that the vendor value is back:

$ sudo systemctl revert NetworkManager-wait-online.service
$ systemctl cat NetworkManager-wait-online.service

Do not reduce the timeout just to hide a failure. A shorter value can let dependent units proceed while the network is still unavailable, turning a visible boot delay into a less obvious mount or application failure.