Tencent/matrix · error · GradleException

sign apk occur error!

Error message

sign apk occur error!

What it means

Thrown by ApkUtil.signApk after executing an external apksigner/jarsigner command to sign the shrunk APK; any non-zero exit status becomes GradleException('sign apk occur error!'). The signing tool's stdout/stderr is consumed by waitForProcessOutput, so the root cause is in the process output. It means the APK was not signed successfully.

Solutions

  1. Re-run with gradle --info or execute the same apksigner command manually to see the signer's real error
  2. Verify keystore file path, store password, key alias and key password in the Matrix shrinker config are correct
  3. Confirm the signing tool path (apksigner from build-tools, or jarsigner from JDK) exists and matches your JDK version
  4. Ensure the unsigned APK input exists and is valid before signing

Example fix

// before
signApk(inputApk, outApk, wrongKeystore, wrongPass, alias)
// after
assert new File(keystorePath).exists()
signApk(inputApk, outApk, keystorePath, correctStorePassword, keyAlias)
Defensive patterns

Strategy: validation

Validate before calling

assert new File(keystorePath).exists() : 'keystore missing'
assert signingTool != null && new File(signingTool).exists() : 'apksigner/jarsigner not found'
assert storePassword && keyAlias && keyPassword : 'signing credentials incomplete'

Try / catch

try {
    ApkUtil.signApk(inputApk, outputApk, keystore, pass, alias)
} catch (GradleException e) {
    logger.error('APK signing failed; verify keystore credentials and signing tool path', e)
    throw e
}

Prevention

When it happens

Trigger: Calling signApk(...) when the keystore path/password/alias is wrong, the signing tool (apksigner/jarsigner) path is invalid, the JDK keytool is missing, the keystore file doesn't exist, or the APK was modified after an earlier signature making signing fail.

Common situations: CI environments with missing or wrong signingConfig credentials; expired keystore passwords after a change; using JDK without jarsigner on PATH; v1/v2 signing scheme incompatibilities with older build tools.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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

Appendix: source

Thrown at matrix/matrix-android/matrix-gradle-plugin/src/main/java/com/tencent/matrix/shrinker/ApkUtil.java:372

                "--ks-pass", "pass:" + signingConfig.getStorePassword(),
                "--key-pass", "pass:" + signingConfig.getKeyPassword(),
                "--ks-key-alias", signingConfig.getKeyAlias()));

        if (signingConfig.isV1SigningEnabled()) {
            commandList.add("--v1-signing-enabled");
        }

        if (signingConfig.isV2SigningEnabled()) {
            commandList.add("--v2-signing-enabled");
        }
        commandList.add(apkFilePath);
        processBuilder.command(commandList);
        //Log.i(TAG, "%s", processBuilder.command())
        Process process = processBuilder.start();
//        process.waitForProcessOutput(System.out, System.err);
        waitForProcessOutput(process);
        if (process.exitValue() != 0) {
            throw new GradleException("sign apk occur error!");
        }
    }

    public static void zipAlignApk(String inputFile, String outputFile, String zipAlignPath) throws GradleException, IOException, InterruptedException {
        ProcessBuilder processBuilder = new ProcessBuilder();
        processBuilder.command(zipAlignPath, "-f", "4", inputFile, outputFile);
        Process process = processBuilder.start();
//        process.waitForProcessOutput(System.out, System.err);
        waitForProcessOutput(process);
        if (process.exitValue() != 0) {
            throw new GradleException("zipalign apk occur error!");
        }
    }

}

View on GitHub (pinned to 3b8293bd65)