{"record":{"id":"44cb6637d2abd226","repo":"Tencent/tinker","slug":"bad-dex-patch-file-version","errorCode":null,"errorMessage":"bad dex patch file version: ","messagePattern":"bad dex patch file version: ","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"tinker-commons/src/main/java/com/tencent/tinker/commons/dexpatcher/struct/DexPatchFile.java","lineNumber":86,"sourceCode":"    public DexPatchFile(File file) throws IOException {\n        this.buffer = new DexDataBuffer(ByteBuffer.wrap(FileUtils.readFile(file)));\n        init();\n    }\n\n    public DexPatchFile(InputStream is) throws IOException {\n        this.buffer = new DexDataBuffer(ByteBuffer.wrap(FileUtils.readStream(is)));\n        init();\n    }\n\n    private void init() {\n        byte[] magic = this.buffer.readByteArray(MAGIC.length);\n        if (CompareUtils.uArrCompare(magic, MAGIC) != 0) {\n            throw new IllegalStateException(\"bad dex patch file magic: \" + Arrays.toString(magic));\n        }\n\n        this.version = this.buffer.readShort();\n        if (this.version != VERSION_02 && this.version != VERSION_03) {\n            throw new IllegalStateException(\"bad dex patch file version: \" + this.version);\n        }\n\n        if (this.version > VERSION_02) {\n            this.oldDexAPI = this.buffer.readInt();\n            this.patchedDexAPI = this.buffer.readInt();\n        }\n        this.patchedDexSize = this.buffer.readInt();\n        this.firstChunkOffset = this.buffer.readInt();\n        this.patchedStringIdSectionOffset = this.buffer.readInt();\n        this.patchedTypeIdSectionOffset = this.buffer.readInt();\n        this.patchedProtoIdSectionOffset = this.buffer.readInt();\n        this.patchedFieldIdSectionOffset = this.buffer.readInt();\n        this.patchedMethodIdSectionOffset = this.buffer.readInt();\n        if (this.version > DexPatchFile.VERSION_02) {\n            this.patchedCallSiteIdSectionOffset = this.buffer.readInt();\n            this.patchedMethodHandlesSectionOffset = this.buffer.readInt();\n        }\n        this.patchedClassDefSectionOffset = this.buffer.readInt();","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/Tencent/tinker/blob/1b7ea02c239840f563ea64fb5bd286eb98d4011e/tinker-commons/src/main/java/com/tencent/tinker/commons/dexpatcher/struct/DexPatchFile.java#L68-L104","documentation":"IllegalStateException from DexPatchFile.init: the magic matched but the patch format version short is neither VERSION_02 nor VERSION_03. The parsing code only understands these two formats, so patches written by a different (newer or older) generator are rejected.","triggerScenarios":"Applying a dex patch produced by a Tinker gradle plugin whose DexPatchGenerator writes a different version field than the DexPatchFile reader in the runtime loader accepts.","commonSituations":"Version skew: patch built with newer Tinker (new format) but app embeds an older tinker-android loader, or vice versa; third-party tools emitting their own patch format versions.","solutions":["Align Tinker versions: use the same release for the gradle plugin (tinker-patch-gradle-plugin) and the app's tinker-android dependency","Upgrade both sides together after checking the supported format matrix","Regenerate the patch with the matching toolchain"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"short v = patchFileVersion; // read header short before full parse\nif (v != DexPatchFile.VERSION_02 && v != DexPatchFile.VERSION_03) {\n    throw new IOException(\"unsupported patch format \" + v + \"; align Tinker versions\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    new DexPatchFile(stream);\n} catch (IllegalStateException e) {\n    if (String.valueOf(e.getMessage()).startsWith(\"bad dex patch file version\")) {\n        // version skew: regenerate patch with matching plugin or upgrade loader\n    } else { throw e; }\n}","preventionTips":["Lock tinker gradle plugin and tinker-android dependencies to the same release line","Upgrade both ends together and run an end-to-end patch test before rollout"],"tags":["dexpatcher","version-mismatch","tinker","patch-format"],"backgroundTag":null,"analyzedSha":"1b7ea02c239840f563ea64fb5bd286eb98d4011e","analyzedAt":"2026-08-14T15:16:52.110Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}