{"record":{"id":"de9eb0f34cda993d","repo":"prometheus/node_exporter","slug":"failed-to-retrieve-bss-for-device-s-v","errorCode":null,"errorMessage":"failed to retrieve BSS for device %s: %v","messagePattern":"failed to retrieve BSS for device (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"collector/wifi_linux.go","lineNumber":201,"sourceCode":"\t\tch <- prometheus.MustNewConstMetric(\n\t\t\twifiInterfaceFrequencyHertz,\n\t\t\tprometheus.GaugeValue,\n\t\t\tmHzToHz(ifi.Frequency),\n\t\t\tifi.Name,\n\t\t)\n\n\t\t// When a statistic is not available for a given interface, package wifi\n\t\t// returns a os.ErrNotExist error.  We leverage this to only export\n\t\t// metrics which are actually valid for given interface types.\n\n\t\tbss, err := stat.BSS(ifi)\n\t\tswitch {\n\t\tcase err == nil:\n\t\t\tc.updateBSSStats(ch, ifi.Name, bss)\n\t\tcase errors.Is(err, os.ErrNotExist):\n\t\t\tc.logger.Debug(\"BSS information not found for wifi device\", \"name\", ifi.Name)\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"failed to retrieve BSS for device %s: %v\",\n\t\t\t\tifi.Name, err)\n\t\t}\n\n\t\tstations, err := stat.StationInfo(ifi)\n\t\tswitch {\n\t\tcase err == nil:\n\t\t\tfor _, station := range stations {\n\t\t\t\tc.updateStationStats(ch, ifi.Name, station)\n\t\t\t}\n\t\tcase errors.Is(err, os.ErrNotExist):\n\t\t\tc.logger.Debug(\"station information not found for wifi device\", \"name\", ifi.Name)\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"failed to retrieve station info for device %q: %v\",\n\t\t\t\tifi.Name, err)\n\t\t}\n\t}\n\n\treturn nil","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/prometheus/node_exporter/blob/17ddd77c59ba27e1508e9f7894b1e55b44d6aed3/collector/wifi_linux.go#L183-L219","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If the interface is not a real station device (monitor/virtual), exclude it or disable the wifi collector with --collector.wifi=false.","Run node_exporter with CAP_NET_ADMIN and confirm the underlying wrapped error is not EPERM.","Retry after the interface settles; transient netlink errors during scan cycles can abort the scrape.","Upgrade kernel/wifi driver so BSS queries return a clean empty result instead of an error."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Probe per-device availability before relying on BSS stats\nout, err := exec.Command(\"iw\", \"dev\", ifname, \"link\").Output()\nif err != nil {\n    // device does not support BSS queries; don't expect wifi_bss metrics\n}","typeGuard":"// Go: classify the error from the library\nswitch {\ncase errors.Is(err, os.ErrNotExist):\n    // expected: interface type has no BSS info; ignore\ncase errors.Is(err, os.ErrPermission):\n    // fix capabilities\ndefault:\n    // real driver/netlink failure\n}","tryCatchPattern":"if err := coll.Update(ch); err != nil {\n    var devName string\n    if fmt.Sprint(err) != \"\" && strings.Contains(err.Error(), \"failed to retrieve BSS for device\") {\n        logger.Warn(\"BSS query failed; falling back to interface-level wifi metrics\", \"err\", err)\n        return nil\n    }\n    return err\n}","preventionTips":["Avoid enabling the wifi collector against virtual/monitor interfaces with flaky drivers","Keep wifi drivers and firmware updated on monitored hosts","Grant CAP_NET_ADMIN to the exporter process","Treat per-interface stat errors as non-fatal in your scrape wrapper and alert on missing series instead"],"tags":["linux","netlink","wifi","collector"],"backgroundTag":"network-request-failed","analyzedSha":"17ddd77c59ba27e1508e9f7894b1e55b44d6aed3","analyzedAt":"2026-09-07T17:54:06.211Z","contentChangedAt":"2026-09-07T17:54:06.211Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}