eBPF functionality is only supported on Linux, current…

Error message

eBPF functionality is only supported on Linux, current platform is not Linux

What it means

ErrEBPFSupportedOnlyOnLinux is a package-level sentinel error returned by EbpfEngineLoad and getBootTimeNanos in build-tag-guarded files (ebpf_other.go) compiled on non-Linux platforms. The eBPF/XDP deny-path engine depends on Linux kernel facilities (XDP programs, BPF maps, /proc boot time), so any attempt to use it elsewhere fails immediately with this error.

Solutions

Run nhp-ac on Linux (kernel >= the version required by cilium/ebpf) with root/CAP_BPF+CAP_NET_ADMIN
Set filter_mode = 0 (FilterMode_IPTABLES) in the AC config on non-Linux platforms
Guard code with runtime.GOOS == "linux" before selecting the eBPF engine
Ensure the eBPF object files were compiled (make ebpf requires clang) if on Linux but still hitting the stub

Example fix

// before
if a.config.FilterMode == FilterMode_EBPFXDP {
    err := ebpf.EbpfEngineLoad(...)
// after
if a.config.FilterMode == FilterMode_EBPFXDP {
    if runtime.GOOS != "linux" {
        log.Warn("eBPF unsupported on %s, falling back to iptables", runtime.GOOS)
        a.config.FilterMode = FilterMode_IPTABLES
    } else if err := ebpf.EbpfEngineLoad(...); err != nil { ... }

Defensive patterns

Strategy: validation

Validate before calling

if runtime.GOOS != "linux" {
	return fmt.Errorf("eBPF requires Linux, got %s", runtime.GOOS)
}
if ! capabilityHasCAPBPF() { ... }

Try / catch

if err := ebpf.EbpfEngineLoad(dir, lvl, id); err != nil {
	if errors.Is(err, ebpf.ErrEBPFSupportedOnlyOnLinux) {
		log.Warn("falling back to iptables filter mode")
		conf.FilterMode = ac.FilterMode_IPTABLES
	}
}

Prevention

Set filter_mode=iptables on non-Linux dev machines
Gate eBPF paths on runtime.GOOS and build tags
Document kernel/capability requirements (root or CAP_BPF/CAP_NET_ADMIN)

When it happens

Trigger: Calling endpoints/ac/ebpf.EbpfEngineLoad (or nhp/utils/ebpf getBootTimeNanos) on a darwin/windows build, or when the file was compiled without the Linux build tag; also returned when AC FilterMode is FilterMode_EBPFXDP on a non-Linux host.

Common situations: Developer builds nhp-ac on macOS for local dev with filter_mode=ebpf_xdp in config.toml; CI runner on non-Linux OS exercises the eBPF code path; cross-compilation produces a stub build.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of OpenNHP/opennhp@6e04ca5ff0 (2026-09-07). Data as JSON: /api/errors/449aeb9f74cc630d. Report an issue: GitHub.

Appendix: source

Thrown at endpoints/ac/ebpf/ebpf_other.go:13

//go:build !linux

package ebpf

import (
	// "log"

	"fmt"

	"github.com/OpenNHP/opennhp/nhp/log"
)

var ErrEBPFSupportedOnlyOnLinux = fmt.Errorf("eBPF functionality is only supported on Linux, current platform is not Linux")
var (
	DenyLogger *log.Logger
	AcLogger   *log.Logger
)

func EbpfEngineLoad(dirPath string, logLevel int, acId string) error {
	log.Info("eBPF function must be compiled on Linux OS")
	return ErrEBPFSupportedOnlyOnLinux
}

// clean eBPF map file
func CleanupBPFFiles() {
	log.Info("ebpf func must be compile based linux os")
}

View on GitHub (pinned to 6e04ca5ff0)