prometheus/node_exporter · critical

failed to initialize ethtool library

Error message

failed to initialize ethtool library: %w

What it means

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.

Solutions

1. Read the wrapped %w error — it names the underlying netlink/ioctl failure.
2. Run node_exporter with sufficient privileges (CAP_NET_ADMIN) to open ethtool interfaces.
3. Check security modules/seccomp profiles are not blocking AF_NETLINK ethtool sockets.
4. Upgrade github.com/safchain/ethtool dependency / kernel if netlink ethtool API is unsupported; else disable the collector with --collector.ethtool=false.

Example fix

// deployment before: no capabilities
containers:
  - image: prom/node-exporter

// after: grant capability needed by ethtool
containers:
  - image: prom/node-exporter
    securityContext:
      capabilities:
        add: ["SYS_TIME", "NET_ADMIN"]

const { execSync } = require('child_process');
try {
  execSync('ethtool --version', { stdio: 'ignore' });
} catch {
  console.warn('ethtool facilities unavailable/privileges missing — ethtool collector init may fail; add NET_ADMIN or disable --collector.ethtool');
}

try {
  await startNodeExporter({ collectors: ['ethtool'] });
} catch (e) {
  if (String(e).includes('failed to initialize ethtool library')) {
    console.error('ethtool init failed: check NET_ADMIN capability, seccomp/netlink policy, or disable --collector.ethtool');
  } else throw e;
}

When it happens

Trigger: ethtool.NewEthtool() returns an error inside makeEthtoolCollector during collector creation (node_exporter startup or test setup).

Common situations: 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.

Related errors

• could not get link modes
• failed to open sysfs
• could not get net class info
• couldn't connect rtnetlink
• couldn't get links

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

Appendix: source

Thrown at collector/ethtool_linux.go:94

	ethtool        Ethtool
	deviceFilter   deviceFilter
	infoDesc       *prometheus.Desc
	metricsPattern *regexp.Regexp
	logger         *slog.Logger
}

// makeEthtoolCollector is the internal constructor for EthtoolCollector.
// This allows NewEthtoolTestCollector to override its .ethtool interface
// for testing.
func makeEthtoolCollector(logger *slog.Logger) (*ethtoolCollector, error) {
	fs, err := sysfs.NewFS(*sysPath)
	if err != nil {
		return nil, fmt.Errorf("failed to open sysfs: %w", err)
	}

	e, err := ethtool.NewEthtool()
	if err != nil {
		return nil, fmt.Errorf("failed to initialize ethtool library: %w", err)
	}

	if *ethtoolDeviceInclude != "" {
		logger.Info("Parsed flag --collector.ethtool.device-include", "flag", *ethtoolDeviceInclude)
	}
	if *ethtoolDeviceExclude != "" {
		logger.Info("Parsed flag --collector.ethtool.device-exclude", "flag", *ethtoolDeviceExclude)
	}
	if *ethtoolIncludedMetrics != "" {
		logger.Info("Parsed flag --collector.ethtool.metrics-include", "flag", *ethtoolIncludedMetrics)
	}

	// Pre-populate some common ethtool metrics.
	return &ethtoolCollector{
		fs:             fs,
		ethtool:        &ethtoolLibrary{e},
		deviceFilter:   newDeviceFilter(*ethtoolDeviceExclude, *ethtoolDeviceInclude),
		metricsPattern: regexp.MustCompile(*ethtoolIncludedMetrics),

View on GitHub (pinned to 17ddd77c59)