What causes "Unknown Java structure" in Konloch/bytecode-viewer?

Recompile or re-obtain a clean copy of the class file; the bytes are structurally invalid.

Konloch/bytecode-viewer · error · ClassFileFormatException

Unknown Java structure

Error message

Unknown Java structure

What it means

After parsing the constant pool, ExtractDirectoryPath reads this_class, an index into the constants array. If the index exceeds the array bounds, the file's structure is inconsistent with the JVM class-file spec, so a ClassFileFormatException('Unknown Java structure') is thrown. In practice this means the file is malformed, truncated mid-header, or not really a class file that got past the magic check.

Source

Thrown at src/main/java/the/bytecode/club/bytecodeviewer/decompilers/jdgui/JDGUIClassFileUtil.java:66

            if (magic != ClassFileReader.JAVA_MAGIC_NUMBER)
            {
                throw new ClassFileFormatException("Invalid Java .class file");
            }

            /* int minor_version = */
            dis.readUnsignedShort();
            /* int major_version = */
            dis.readUnsignedShort();

            Constant[] constants = DeserializeConstants(dis);

            /* int access_flags = */
            dis.readUnsignedShort();
            int this_class = dis.readUnsignedShort();

            if (this_class > constants.length)
            {
                throw new ClassFileFormatException("Unknown Java structure");
            }
            Constant c = constants[this_class];
            if ((c == null) || (c.getTag() != Constant.CONSTANT_Class))
            {
                throw new ClassFileFormatException("Invalid constant pool");
            }

            c = constants[((ConstantClass) c).getNameIndex()];
            if ((c == null) || (c.getTag() != Constant.CONSTANT_Utf8))
            {
                throw new ClassFileFormatException("Invalid constant pool");
            }

            String internalClassName = ((ConstantUtf8) c).getValue();
            String pathSuffix = internalClassName.replace(INTERNAL_PACKAGE_SEPARATOR, File.separatorChar) + CLASS_FILE_SUFFIX;

            int index = pathToClass.indexOf(pathSuffix);

View on GitHub (pinned to 31430e0033)

Solutions

Recompile or re-obtain a clean copy of the class file; the bytes are structurally invalid.
Check that the file was fully extracted (no truncation) — compare size against the source JAR entry.
Re-run the file through a spec-compliant parser (e.g. javap -v or ASM) to pinpoint where the structure diverges.
If obfuscated/packed, deobfuscate/depack first so the constant pool uses standard tags the simple parser recognizes.
Catch ClassFileFormatException and skip the file in batch processing.

Example fix

// before
String dir = JDGUIClassFileUtil.ExtractDirectoryPath(path); // throws on malformed file

// after
try {
    String dir = JDGUIClassFileUtil.ExtractDirectoryPath(path);
} catch (org.jd.core.v1.service.deserializer.classfile.ClassFileFormatException e) {
    // malformed/unrecognized structure: log and skip this file
}

Defensive patterns

Strategy: try-catch

Validate before calling

ProcessBuilder pb = new ProcessBuilder("javap", "-verify", path);
pb.inheritIO();
int rc = pb.start().waitFor();
if (rc != 0) throw new IllegalStateException("Class file structurally invalid: " + path);

Try / catch

try {
    String dir = JDGUIClassFileUtil.ExtractDirectoryPath(path);
} catch (org.jd.core.v1.service.deserializer.classfile.ClassFileFormatException e) {
    if ("Unknown Java structure".equals(e.getMessage())) {
        logger.warn("Malformed class structure: {}", path); // skip file
    } else {
        throw e;
    }
}

Prevention

Validate class files with a spec-compliant verifier (javap, ASM CheckClassAdapter) before parsing.
Ensure files are fully extracted — truncated files commonly fail here.
Avoid feeding output of custom/partial bytecode rewriters to this lightweight parser.
Treat unknown constant-pool tags as a signal the file needs preprocessing (deobfuscation) first.
Process files individually in a loop with per-file exception handling.

When it happens

Trigger: ExtractDirectoryPath on a corrupt/truncated class file where parsing stops early (DeserializeConstants returns early on an unknown tag, leaving constants shorter than expected) and the subsequent this_class index exceeds constants.length; also hand-crafted or obfuscated files with out-of-range cp indices.

Common situations: Files truncated by incomplete extraction or transfer; classes produced by non-standard tools/old obfuscators emitting constant-pool tags this parser does not know (default case bails out early, shrinking the array); fuzzed or edited binaries.

Related errors

AI-assisted analysis of Konloch/bytecode-viewer@31430e0033 (2026-09-05). Data as JSON: /api/errors/414a91f11be8703d. Report an issue: GitHub.