XTLS/Xray-core · error

LoadLibrary iphlpapi.dll failed

Error message

LoadLibrary iphlpapi.dll failed

What it means

The Windows FindProcess lazily initializes its win32 bindings (sync.Once) and windows.LoadLibrary("iphlpapi.dll") failed; the OS error is chained via Base. iphlpapi.dll ships with every Windows install, so failure means the process environment cannot load it — broken install, DLL search-path hijack block, or a stripped Windows container.

Source

Thrown at common/net/find_process_windows.go:37

const (
	tcpTableFunc    = "GetExtendedTcpTable"
	tcpTablePidConn = 4
	udpTableFunc    = "GetExtendedUdpTable"
	udpTablePid     = 1
)

var (
	getExTCPTable uintptr
	getExUDPTable uintptr

	once    sync.Once
	initErr error
)

func initWin32API() error {
	h, err := windows.LoadLibrary("iphlpapi.dll")
	if err != nil {
		return errors.New("LoadLibrary iphlpapi.dll failed").Base(err)
	}

	getExTCPTable, err = windows.GetProcAddress(h, tcpTableFunc)
	if err != nil {
		return errors.New("GetProcAddress of ", tcpTableFunc, " failed").Base(err)
	}

	getExUDPTable, err = windows.GetProcAddress(h, udpTableFunc)
	if err != nil {
		return errors.New("GetProcAddress of ", udpTableFunc, " failed").Base(err)
	}

	return nil
}

func FindProcess(network, srcIP string, srcPort uint16, destIP string, destPort uint16) (PID int, Name string, AbsolutePath string, err error) {
	once.Do(func() {
		initErr = initWin32API()

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Read the chained Windows error code (module not found vs access denied) to pick the fix
2. Verify with 'rundll32 iphlpapi.dll,GetIfEntry' or check C:\Windows\System32\iphlpapi.dll exists
3. Repair the Windows image (sfc /scannow, DISM RestoreHealth) if the DLL is missing/corrupt
4. Adjust AppLocker/WDAC rules to allow loading iphlpapi.dll, or run outside the restricted policy
5. Disable process-based routing rules if the environment legitimately lacks the DLL

// Windows: verify the DLL is loadable before relying on process rules
h, err := windows.LoadLibrary("iphlpapi.dll")
if err != nil {
    // every FindProcess call will fail with the cached initErr
}

if err != nil && strings.Contains(err.Error(), "LoadLibrary iphlpapi.dll failed") {
    // permanent for this process (sync.Once caches initErr); disable process rules
}

When it happens

Trigger: Running in Windows Server Core / Nano Server images where iphlpapi.dll was removed; AppLocker/WDAC policies blocking DLL loads from the search path; a corrupt system image. The error surfaces on the first FindProcess call and is cached in initErr for all later calls.

Common situations: See trigger scenarios.

Related errors

• GetProcAddress of {tcpTableFunc} failed
• GetProcAddress of {udpTableFunc} failed
• failed to determine if address is local: {err}
• invalid IP address
• not found

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/b489233f28ba7e81. Report an issue: GitHub.