prometheus/node_exporter · error

failed to retrieve BSS for device

Error message

failed to retrieve BSS for device %s: %v

What it means

After enumerating wifi interfaces, the collector calls stat.BSS(ifi) to fetch per-interface BSS (access-point) information over netlink. os.ErrNotExist is treated as 'not applicable for this interface' and only debug-logged, but any other error aborts the scrape with this wrapped message naming the device.

Solutions

1. Identify the named device and check its state with 'iw dev <name> link' / 'iw dev <name> scan'; update or reload the wifi driver if it errors.
2. If the interface is not a real station device (monitor/virtual), exclude it or disable the wifi collector with --collector.wifi=false.
3. Run node_exporter with CAP_NET_ADMIN and confirm the underlying wrapped error is not EPERM.
4. Retry after the interface settles; transient netlink errors during scan cycles can abort the scrape.
5. Upgrade kernel/wifi driver so BSS queries return a clean empty result instead of an error.

// Probe per-device availability before relying on BSS stats
out, err := exec.Command("iw", "dev", ifname, "link").Output()
if err != nil {
    // device does not support BSS queries; don't expect wifi_bss metrics
}

// Go: classify the error from the library
switch {
case errors.Is(err, os.ErrNotExist):
    // expected: interface type has no BSS info; ignore
case errors.Is(err, os.ErrPermission):
    // fix capabilities
default:
    // real driver/netlink failure
}

if err := coll.Update(ch); err != nil {
    var devName string
    if fmt.Sprint(err) != "" && strings.Contains(err.Error(), "failed to retrieve BSS for device") {
        logger.Warn("BSS query failed; falling back to interface-level wifi metrics", "err", err)
        return nil
    }
    return err
}

When it happens

Trigger: stat.BSS(ifi) in wifiCollector.Update returns a non-nil error that is neither nil nor os.ErrNotExist — e.g. netlink receive timeout, permission denied on the NL80211_CMD_GET_SCAN query, or driver returning an unexpected netlink error for the interface.

Common situations: Interfaces in a transitional state (scanning/disconnected) whose driver rejects BSS queries, virtual wifi devices (monitors, MAC80211_hwsim) without scan results plus a driver error, containers lacking permissions, buggy out-of-tree wifi drivers returning non-ENODEV errors instead of a clean empty result.

Related errors

• failed to retrieve wifi interfaces
• failed to retrieve station info for device
• failed to access wifi data
• could not get ARP entries
• failed to get vulnerabilities

AI-assisted analysis of prometheus/node_exporter@17ddd77c59 (2026-09-07). Data as JSON: /api/errors/de9eb0f34cda993d. Report an issue: GitHub.

Appendix: source

Thrown at collector/wifi_linux.go:201

		ch <- prometheus.MustNewConstMetric(
			wifiInterfaceFrequencyHertz,
			prometheus.GaugeValue,
			mHzToHz(ifi.Frequency),
			ifi.Name,
		)

		// When a statistic is not available for a given interface, package wifi
		// returns a os.ErrNotExist error.  We leverage this to only export
		// metrics which are actually valid for given interface types.

		bss, err := stat.BSS(ifi)
		switch {
		case err == nil:
			c.updateBSSStats(ch, ifi.Name, bss)
		case errors.Is(err, os.ErrNotExist):
			c.logger.Debug("BSS information not found for wifi device", "name", ifi.Name)
		default:
			return fmt.Errorf("failed to retrieve BSS for device %s: %v",
				ifi.Name, err)
		}

		stations, err := stat.StationInfo(ifi)
		switch {
		case err == nil:
			for _, station := range stations {
				c.updateStationStats(ch, ifi.Name, station)
			}
		case errors.Is(err, os.ErrNotExist):
			c.logger.Debug("station information not found for wifi device", "name", ifi.Name)
		default:
			return fmt.Errorf("failed to retrieve station info for device %q: %v",
				ifi.Name, err)
		}
	}

	return nil

View on GitHub (pinned to 17ddd77c59)