XTLS/Xray-core · error

failed to list processes

Error message

failed to list processes

What it means

Thrown by the macOS implementation of FindProcess when the sysctl 'kern.proc.all' fails to return the process table (unix.SysctlKinfoProcSlice). The library needs the full kinfo_proc list to compare every process's file-descriptor socket addresses against the queried connection. Without the process table, no PID resolution is possible.

Source

Thrown at common/net/find_process_darwin.go:83

	if err != nil {
		return 0, "", "", errors.New("invalid source IP address: ", srcIP)
	}
	srcAddr = srcAddr.Unmap()

	var dstAddr netip.Addr
	hasDstAddr := false
	if destIP != "" && destPort != 0 {
		dstAddr, err = netip.ParseAddr(destIP)
		if err != nil {
			return 0, "", "", errors.New("invalid destination IP address: ", destIP)
		}
		dstAddr = dstAddr.Unmap()
		hasDstAddr = true
	}

	processes, err := unix.SysctlKinfoProcSlice("kern.proc.all")
	if err != nil {
		return 0, "", "", errors.New("failed to list processes").Base(err)
	}

	var bestPID int32
	bestLevel := darwinSocketNoMatch
	ambiguousBest := false

	for _, process := range processes {
		pid := process.Proc.P_pid
		if pid <= 0 {
			continue
		}

		matchLevel, err := darwinProcessSocketMatchLevel(pid, network, srcAddr, srcPort, dstAddr, destPort, hasDstAddr)
		if err != nil || matchLevel == darwinSocketNoMatch {
			continue
		}
		if matchLevel == darwinSocketExactMatch {
			bestPID = pid

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Run the binary outside sandbox-exec / without sandbox profiles, or grant the process-enum entitlement if the app is hardened-runtime signed
2. Verify manually: sysctl kern.proc.all in a terminal to confirm the sysctl works for your user context
3. Treat process lookup as best-effort: log and continue without process info in routing rules
4. If the caller passes a destination address it can improve matching, but nothing fixes a denied sysctl except removing the sandbox

Example fix

// before
pid, name, path, err := net.FindProcess(network, srcIP, srcPort, dstIP, dstPort)
if err != nil {
    return err // lookup failure aborts routing decision
}

// after
pid, name, path, err := net.FindProcess(network, srcIP, srcPort, dstIP, dstPort)
if err != nil {
    newError("process lookup unavailable, skipping process rules").Base(err).WriteToLog()
    pid, name, path = 0, "", ""
}

// Pre-flight on macOS: verify the sysctl the implementation depends on
procs, err := unix.SysctlKinfoProcSlice("kern.proc.all")
if err != nil || len(procs) == 0 {
    // process lookup will fail; skip process-based rules
}

pid, name, path, err := net.FindProcess(netw, srcIP, srcPort, dstIP, dstPort)
if err != nil {
    newError("process lookup unavailable").Base(err).AtWarning().WriteToLog()
    // route without process info
}

When it happens

Trigger: Calling common/net.FindProcess on macOS when sysctl kern.proc.all returns an error: sandboxed/masqueraded processes (macOS sandbox denies KERN_PROCALL), a hardened-runtime app without the entitlement to enumerate other processes, or kernel memory pressure making the sysctl fail.

Common situations: Running Xray core inside a macOS sandbox (App Store style distribution, iOS-on-mac processes), running under a restricted daemon context, or an extremely loaded system where the sysctl buffer allocation fails.

Related errors

• failed to determine if address is local:
• invalid source IP address:
• invalid destination IP address:
• process not found for connection from ::: to :
• ambiguous process match for connection from ::: to :

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