{"record":{"id":"06fe74ed9a895961","repo":"XTLS/Xray-core","slug":"android-process-lookup-must-be-registered-before-u","errorCode":null,"errorMessage":"android process lookup must be registered before use","messagePattern":"android process lookup must be registered before use","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/net/find_process_android.go","lineNumber":19,"sourceCode":"//go:build android\n\npackage net\n\nimport (\n\t\"github.com/xtls/xray-core/common/errors\"\n)\n\nvar androidProcessFinder func(network, srcIP string, srcPort uint16, destIP string, destPort uint16) (int, string, string, error)\n\nfunc RegisterAndroidProcessFinder(f func(network, srcIP string, srcPort uint16, destIP string, destPort uint16) (int, string, string, error)) {\n\tandroidProcessFinder = f\n}\n\nfunc FindProcess(network, srcIP string, srcPort uint16, destIP string, destPort uint16) (int, string, string, error) {\n\tif androidProcessFinder != nil {\n\t\treturn androidProcessFinder(network, srcIP, srcPort, destIP, destPort)\n\t}\n\treturn 0, \"\", \"\", errors.New(\"android process lookup must be registered before use\")\n}\n","sourceCodeStart":1,"sourceCodeEnd":21,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/common/net/find_process_android.go#L1-L21","documentation":"common/net.FindProcess was called on Android, but no process finder was registered via RegisterAndroidProcessFinder. On Android, Xray-core cannot enumerate /proc or use sysctl the way desktop platforms do, so the lookup function must be injected by the embedding app (e.g. Xray's Android libs via JNI/Go mobile that consult ConnectionOwner).","triggerScenarios":"Building for android/arm with find_process_android.go compiled in and calling FindProcess before (or without ever) calling RegisterAndroidProcessFinder.","commonSituations":"Running Xray-core inside a custom Android app (v2rayNG-style) that updated its libcore bindings and dropped the registration call, or a new embedding that never wired it up.","solutions":["In the Android host app, call mux-adjacent init properly: register the finder at startup, e.g. net.RegisterAndroidProcessFinder(libcore.FindProcess) or the equivalent binding.","Update the embedding library (libcore/Aars) to a version matching the Xray-core version, since the registration contract is version-locked.","If process matching is not needed, disable the features that call FindProcess (e.g. routing rule with 'inboundUser'/process matching or sniffing options that need PID).","For quick tests, run on linux instead where the native finder works without registration."],"exampleFix":"// Android app startup, before starting Xray\n// before: finder never registered, FindProcess always errors\n// after\nimport \"github.com/xtls/xray-core/common/net\"\n\nfunc init() {\n    net.RegisterAndroidProcessFinder(func(network, srcIP string, srcPort uint16, destIP string, destPort uint16) (int, string, string, error) {\n        return owner.FindProcessOwner(network, srcIP, srcPort, destIP, destPort) // implemented via Android ConnectionOwner API\n    })\n}","handlingStrategy":"type-guard","validationCode":"// Register at app startup, before any FindProcess use:\nnet.RegisterAndroidProcessFinder(myFinder) // myFinder implements the owner-lookup contract","typeGuard":null,"tryCatchPattern":"// Expose a readiness check:\nvar androidProcessFinderRegistered atomic.Bool\nfunc RegisterAndroidProcessFinder(f ...) { androidProcessFinder = f; androidProcessFinderRegistered.Store(true) }\n// callers: if !androidProcessFinderRegistered.Load() { skip process lookup }","preventionTips":["Register the finder during app initialization, before starting the Xray instance.","Keep the libcore binding version in lockstep with the Xray-core version.","Disable routing features that need process lookup when registration is impossible."],"tags":["android","platform","process-lookup","integration","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}