{"record":{"id":"e82350c83a7e093f","repo":"Tencent/matrix","slug":"fail-to-do-hook-common-pre-hook-initialize","errorCode":null,"errorMessage":"Fail to do hook common pre-hook initialize.","messagePattern":"Fail to do hook common pre-hook initialize\\.","errorType":"exception","errorClass":"HookFailedException","httpStatus":null,"severity":"error","filePath":"matrix/matrix-android/matrix-hooks/src/main/java/com/tencent/matrix/hook/HookManager.java","lineNumber":78,"sourceCode":"            synchronized (mPendingHooks) {\n                if (mPendingHooks.isEmpty()) {\n                    return;\n                }\n            }\n            if (!mHasNativeInitialized) {\n                try {\n                    if (mNativeLibLoader != null) {\n                        mNativeLibLoader.loadLibrary(\"matrix-hookcommon\");\n                    } else {\n                        System.loadLibrary(\"matrix-hookcommon\");\n                    }\n                } catch (Throwable e) {\n                    MatrixLog.printErrStackTrace(TAG, e, \"\");\n                    return;\n                }\n\n                if (!doPreHookInitializeNative(mEnableDebug)) {\n                    throw new HookFailedException(\"Fail to do hook common pre-hook initialize.\");\n                }\n\n                commitHooksLocked();\n\n                doFinalInitializeNative(mEnableDebug);\n                mHasNativeInitialized = true;\n            } else {\n                commitHooksLocked();\n            }\n        }\n    }\n\n    private boolean enableLibCxxSharedCheck = false;\n    public HookManager enableLibCxxSharedCheck(boolean enable) {\n        enableLibCxxSharedCheck = enable;\n        return this;\n    }\n","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/Tencent/matrix/blob/3b8293bd65d47eeea7caf1f32a3a5d4d5eab60e7/matrix/matrix-android/matrix-hooks/src/main/java/com/tencent/matrix/hook/HookManager.java#L60-L96","documentation":"HookManager.commitHooks() drives Matrix's native hook initialization. Before committing the registered hooks it calls doPreHookInitializeNative(mEnableDebug); if that native step returns false it throws HookFailedException(\"Fail to do hook common pre-hook initialize.\"). This means the native hook engine could not complete its common pre-hook setup (e.g. locating hooks, ELF symbol resolution, inline hook installation failed at the native layer).","triggerScenarios":"Calling HookManager.commitHooks() when the underlying native pre-hook initialization (doPreHookInitializeNative) returns false — typically because the native library could not hook the target functions on this device/ROM, symbols were stripped, or Matrix's native plugin (.so) was not properly packaged/loaded.","commonSituations":"Running on an unusual Android ROM or architecture where inline hooks are unsupported; missing or mismatched .abi .so libraries in the APK (e.g. only arm64 packaged but running on armeabi-v7a); a Matrix version upgrade changing native init requirements; SELinux/hardened environments blocking memory patching.","solutions":["Check MatrixLog output just before the throw for native-side failure details, and inspect logcat for the hooking native library's errors.","Verify all required ABIs' .so files (libmatrix-hook.so etc.) are packaged in the APK and match the device ABI.","Update Matrix to the latest version — older native hook code fails on newer ROMs.","If the device/ROM is unsupported, wrap commitHooks() in try-catch and degrade gracefully (run without hooks) instead of crashing."],"exampleFix":"// before\nnew HookManager().addHook(myHook).commitHooks();\n// after\ntry {\n    new HookManager().addHook(myHook).commitHooks();\n} catch (HookFailedException e) {\n    MatrixLog.e(TAG, \"native hook init failed, running without hooks\", e);\n}","handlingStrategy":"try-catch","validationCode":"// Verify the native libs for the device ABI are present before enabling hooks\nString abi = Build.SUPPORTED_ABIS[0];\nboolean nativeReady = Arrays.asList(ApkAbiChecker.getPackagedAbis(context)).contains(abi);","typeGuard":null,"tryCatchPattern":"try {\n    hookManager.addHook(hook).commitHooks();\n} catch (HookFailedException e) {\n    MatrixLog.e(TAG, \"hook init failed; continuing without native hooks\", e);\n    // degrade: disable features that depend on hooks\n}","preventionTips":["Package .so libraries for every ABI you ship; verify with apkanalyzer.","Keep Matrix updated for newer ROM/architectures.","Treat native hooks as best-effort: catch HookFailedException and degrade rather than crash."],"tags":["native-hook","jni","android","initialization"],"backgroundTag":"module-init-failed","analyzedSha":"3b8293bd65d47eeea7caf1f32a3a5d4d5eab60e7","analyzedAt":"2026-09-08T08:01:39.722Z","contentChangedAt":"2026-09-08T08:01:39.722Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}