{"record":{"id":"48fe6626bb60f3d9","repo":"prometheus/node_exporter","slug":"failed-to-initialize-ethtool-library-w","errorCode":null,"errorMessage":"failed to initialize ethtool library: %w","messagePattern":"failed to initialize ethtool library: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"collector/ethtool_linux.go","lineNumber":94,"sourceCode":"\tethtool        Ethtool\n\tdeviceFilter   deviceFilter\n\tinfoDesc       *prometheus.Desc\n\tmetricsPattern *regexp.Regexp\n\tlogger         *slog.Logger\n}\n\n// makeEthtoolCollector is the internal constructor for EthtoolCollector.\n// This allows NewEthtoolTestCollector to override its .ethtool interface\n// for testing.\nfunc makeEthtoolCollector(logger *slog.Logger) (*ethtoolCollector, error) {\n\tfs, err := sysfs.NewFS(*sysPath)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to open sysfs: %w\", err)\n\t}\n\n\te, err := ethtool.NewEthtool()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to initialize ethtool library: %w\", err)\n\t}\n\n\tif *ethtoolDeviceInclude != \"\" {\n\t\tlogger.Info(\"Parsed flag --collector.ethtool.device-include\", \"flag\", *ethtoolDeviceInclude)\n\t}\n\tif *ethtoolDeviceExclude != \"\" {\n\t\tlogger.Info(\"Parsed flag --collector.ethtool.device-exclude\", \"flag\", *ethtoolDeviceExclude)\n\t}\n\tif *ethtoolIncludedMetrics != \"\" {\n\t\tlogger.Info(\"Parsed flag --collector.ethtool.metrics-include\", \"flag\", *ethtoolIncludedMetrics)\n\t}\n\n\t// Pre-populate some common ethtool metrics.\n\treturn &ethtoolCollector{\n\t\tfs:             fs,\n\t\tethtool:        &ethtoolLibrary{e},\n\t\tdeviceFilter:   newDeviceFilter(*ethtoolDeviceExclude, *ethtoolDeviceInclude),\n\t\tmetricsPattern: regexp.MustCompile(*ethtoolIncludedMetrics),","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/prometheus/node_exporter/blob/17ddd77c59ba27e1508e9f7894b1e55b44d6aed3/collector/ethtool_linux.go#L76-L112","documentation":"After opening sysfs, makeEthtoolCollector initializes the ethtool library with ethtool.NewEthtool(), which opens the netlink/ioctl interfaces needed to query NIC statistics. If initialization fails, the constructor returns 'failed to initialize ethtool library' and the ethtool collector cannot be created. This reflects an OS-level inability to set up ethtool access, not a per-device problem.","triggerScenarios":"ethtool.NewEthtool() returns an error inside makeEthtoolCollector during collector creation (node_exporter startup or test setup).","commonSituations":"Kernels/netlink not available or mismatched ethtool-go dependency; running without sufficient privileges to open ethtool sockets; restricted environments (seccomp/AppArmor blocking netlink); broken interface between the sysfs and ethtool library versions.","solutions":["Read the wrapped %w error — it names the underlying netlink/ioctl failure.","Run node_exporter with sufficient privileges (CAP_NET_ADMIN) to open ethtool interfaces.","Check security modules/seccomp profiles are not blocking AF_NETLINK ethtool sockets.","Upgrade github.com/safchain/ethtool dependency / kernel if netlink ethtool API is unsupported; else disable the collector with --collector.ethtool=false."],"exampleFix":"// deployment before: no capabilities\ncontainers:\n  - image: prom/node-exporter\n\n// after: grant capability needed by ethtool\ncontainers:\n  - image: prom/node-exporter\n    securityContext:\n      capabilities:\n        add: [\"SYS_TIME\", \"NET_ADMIN\"]","handlingStrategy":"try-catch","validationCode":"const { execSync } = require('child_process');\ntry {\n  execSync('ethtool --version', { stdio: 'ignore' });\n} catch {\n  console.warn('ethtool facilities unavailable/privileges missing — ethtool collector init may fail; add NET_ADMIN or disable --collector.ethtool');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await startNodeExporter({ collectors: ['ethtool'] });\n} catch (e) {\n  if (String(e).includes('failed to initialize ethtool library')) {\n    console.error('ethtool init failed: check NET_ADMIN capability, seccomp/netlink policy, or disable --collector.ethtool');\n  } else throw e;\n}","preventionTips":["Grant CAP_NET_ADMIN to node_exporter where ethtool stats are required.","Verify seccomp/AppArmor profiles allow AF_NETLINK ethtool sockets.","Keep the ethtool Go dependency and kernel in supported combinations.","Deploy the ethtool collector only on hosts where NIC stats are needed."],"tags":["linux","ethtool","network","netlink","startup"],"backgroundTag":"module-init-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"}