Tencent/tinker · error · DexException

string index out of bound: {}, perhaps you need to enable fo

Error message

string index out of bound: {}, perhaps you need to enable force jumbo mode.

What it means

Dex string indices are 16-bit for the const-string instruction, so an index above 0xFFFF cannot be encoded. InstructionWriter.visitOneRegisterInsn upgrades CONST_STRING to CONST_STRING/JUMBO automatically, but only when an InstructionPromoter is attached (this.hasPromoter); without one, an oversized index is rejected with this DexException. The message itself points at the remedy: enable force-jumbo mode.

Source

Thrown at third-party/aosp-dexutils/src/main/java/com/tencent/tinker/android/dx/instruction/InstructionWriter.java:119

        currRegF = 0;
        currRegG = 0;

        InstructionCodec.encode(codeOut, this);
    }

    public void visitOneRegisterInsn(int currentAddress, int opcode, int index, int indexType, int target, long literal, int a) {
        if (this.hasPromoter) {
            target = this.insnPromoter.getPromotedAddress(target);
        }

        if (opcode == Opcodes.CONST_STRING) {
            if (this.hasPromoter) {
                if (index > 0xFFFF) {
                    opcode = Opcodes.CONST_STRING_JUMBO;
                }
            } else {
                if (index > 0xFFFF) {
                    throw new DexException("string index out of bound: " + Hex.u4(index)
                            + ", perhaps you need to enable force jumbo mode.");
                }
            }
        }

        currOpcode = opcode;
        currIndex = index;
        currTarget = target;
        currLiteral = literal;
        currRegisterCount = 1;
        currRegA = a;
        currRegB = 0;
        currRegC = 0;
        currRegD = 0;
        currRegE = 0;
        currRegF = 0;
        currRegG = 0;

View on GitHub (pinned to 1b7ea02c23)

Solutions

1. Enable force-jumbo mode so const-string is always emitted (or upgraded) to const-string/jumbo — in tinker's gradle config set `dexmode`/jumbo options (e.g. `tinkerPatch { buildConfig { ... } }` plus dx/d8 `--force-jumbo` in your build's dexOptions).
2. Attach an InstructionPromoter to the InstructionWriter (hasPromoter = true) so oversized indices are auto-upgraded to CONST_STRING_JUMBO instead of throwing.
3. Reduce the string count below 65,536 (strip unused generated strings, shrink resources, split dex via multidex) so plain 16-bit indices suffice.

Example fix

// before: writer without promoter throws on index > 0xFFFF
InstructionWriter writer = new InstructionWriter(dexBuffer);
writer.visitOneRegisterInsn(addr, Opcodes.CONST_STRING, stringIdx, ...);

// after: attach the promoter so const-string is upgraded to const-string/jumbo
InstructionPromoter promoter = new InstructionPromoter(dexBuffer);
InstructionWriter writer = new InstructionWriter(dexBuffer, promoter);
writer.visitOneRegisterInsn(addr, Opcodes.CONST_STRING, stringIdx, ...);

// Pre-check the string table size before writing instructions
boolean needsJumbo(com.tencent.tinker.android.dex.Dex dex) {
    return dex.tableOfContents.stringIds.size > 0x10000;
}
// if needsJumbo(dex) is true, attach an InstructionPromoter or force-jumbo in the build

try {
    writer.visitOneRegisterInsn(addr, opcode, index, ...);
} catch (com.tencent.tinker.android.dex.DexException e) {
    if (e.getMessage() != null && e.getMessage().contains("jumbo")) {
        throw new IllegalStateException("string table exceeds 64K; enable force jumbo mode in the build config", e);
    }
    throw e;
}

When it happens

Trigger: Writing a dex that references more than 65,536 strings while using InstructionWriter without a promoter attached, so a const-string whose string-id index exceeds 0xFFFF has no jumbo form to escape into.

Common situations: Apps with enormous string tables (generated code, many resources/R strings, big native-binding layers) exceeding the 64K string-id limit; building or patching such a dex through tinker's dex writer with jumbo promotion disabled; switching a build from dx/legacy jumbo-opcode mode to d8 without the equivalent setting.

Related errors

• file is null.
• Expected ${DEX_IN_JAR_NAME} in ${file}
• unknown output extension: ${file}
• Unexpected type: ${type}
• invalid LEB128 sequence

AI-assisted analysis of Tencent/tinker@1b7ea02c23 (2026-08-14). Data as JSON: /api/errors/567033e49e945350. Report an issue: GitHub.