What causes "Fail to do hook common pre-hook initialize." in Tencent/matrix?

Check MatrixLog output just before the throw for native-side failure details, and inspect logcat for the hooking native library's errors.

Tencent/matrix · error · HookFailedException

Fail to do hook common pre-hook initialize.

Error message

Fail to do hook common pre-hook initialize.

What it means

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).

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.

Example fix

// before
new HookManager().addHook(myHook).commitHooks();
// after
try {
    new HookManager().addHook(myHook).commitHooks();
} catch (HookFailedException e) {
    MatrixLog.e(TAG, "native hook init failed, running without hooks", e);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify the native libs for the device ABI are present before enabling hooks
String abi = Build.SUPPORTED_ABIS[0];
boolean nativeReady = Arrays.asList(ApkAbiChecker.getPackagedAbis(context)).contains(abi);

Try / catch

try {
    hookManager.addHook(hook).commitHooks();
} catch (HookFailedException e) {
    MatrixLog.e(TAG, "hook init failed; continuing without native hooks", e);
    // degrade: disable features that depend on hooks
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of Tencent/matrix@3b8293bd65 (2026-09-08). Data as JSON: /api/errors/e82350c83a7e093f. Report an issue: GitHub.

Appendix: source

Thrown at matrix/matrix-android/matrix-hooks/src/main/java/com/tencent/matrix/hook/HookManager.java:78

            synchronized (mPendingHooks) {
                if (mPendingHooks.isEmpty()) {
                    return;
                }
            }
            if (!mHasNativeInitialized) {
                try {
                    if (mNativeLibLoader != null) {
                        mNativeLibLoader.loadLibrary("matrix-hookcommon");
                    } else {
                        System.loadLibrary("matrix-hookcommon");
                    }
                } catch (Throwable e) {
                    MatrixLog.printErrStackTrace(TAG, e, "");
                    return;
                }

                if (!doPreHookInitializeNative(mEnableDebug)) {
                    throw new HookFailedException("Fail to do hook common pre-hook initialize.");
                }

                commitHooksLocked();

                doFinalInitializeNative(mEnableDebug);
                mHasNativeInitialized = true;
            } else {
                commitHooksLocked();
            }
        }
    }

    private boolean enableLibCxxSharedCheck = false;
    public HookManager enableLibCxxSharedCheck(boolean enable) {
        enableLibCxxSharedCheck = enable;
        return this;
    }

View on GitHub (pinned to 3b8293bd65)