JEP 136: Enhanced Verification Errors

Summary

Provide additional contextual information about bytecode-verification errors to ease diagnosis of bytecode or stackmap deficiencies in the field.

Goals

Bytecodes are verified by the JVM's bytecode verifier. Bytecodes emitted by the JDK's javac compiler generally result in highly conformant bytecode. However, there are other tools and packages that modify bytecode for various reasons, including instrumentation and debugging. Occasionally, post-processing bytecode results in a VerifyError. Currently, the message associated with the error is rather terse and non-specific. The purpose of this feature is to expand the information available when a VerifyError occurs in modern classfiles so that a developer can more quickly resolve the problem.

Non-Goals

While additional data about errors can be provided, it is not the goal to provide "all possible" data about an error, especially in cases where additional data can be obtained by other means. For instance, while the actual bytecode where the problem occurs may be included in an error message, it may not be disassembled into human-readable form. Additionally the state of the system such as loaded classes and their relationships are not provided as this information is available using other mechanisms.

This extra data will only be available and displayed for errors that are generated by the type-checking verifier. Classfiles with a version less than 50 are verified using the inferencing verifier. Errors generated by the inferencing verifier will not change.

The format of the error message and it's data are not official nor fully specified, and are subject to change in any release.

Success Metrics

This project is considered successful if the additional data provided is used by any single engineer to diagnose a real verification error situation. Given the unpredictability of the problem, and the continuing resistance of engineers to allow implanted tracking chips in their brains, there really is no useful metric that can be applied in this case. We have to rely upon common sense and experience in determining what is likely to be useful, which is historically a notoriously hard thing to quantify.

Motivation

Verification errors are hard to decipher. The current messages attached to VerifyError messages are cryptic and provide very little help in pinpointing where and why the bytecode or stackmap is flawed.

Description

There are two parts to this project. The first is the exposure of a previously internal flag which traces the verification project, and the second an augmentation of the messages contained in a VerifyError with additional contextual information.

The flag which turns on verification tracing was previously an internal global flag which required a change to the source and a recompile of the JVM (in debug mode) to enable. This project turns that flag into the diagnostic flag, 'VerboseVerification'. As such, verification tracing can be turned on (even in product mode) using the command-line flags: "-XX:+UnlockDiagnosticVMOptions -XX:+VerboseVerification"

When run with this flag enabled, the JVM will output tracing information to stdout. This tracing information details which methods are being verified, what mechanism is used for verification, the method's stackmap table. and in debug mode, each instruction's bci, opcode, and current frame state.

In addition, the traditional error message included in thrown VerifyError instance is augmented with the following detailed information: the exact location where the error was detected (class and method name plus bytecode offset); a more detailed error notification which details the origins of any referenced types (if applicable); the current analysis frame state (if applicable); a hex dump of the bytecode; a textual representation of the exception handler table; a textual representation of the stack map table.

The additional error details are formatted into sections and present in a multi-line format in the exception message. The original error message is also unchanged and present at the beginning of the exception message.

Alternatives

One alternative is to not augment with detailed error messages unless a command-line flag is present. This is still a possibility, but since VerifyErrors are rare it is assumed that having extra details by default will not cause any problems.

Testing

Existing test suites for the bytecode verifier can be used to validate this feature. Some tests however, might need to be enhanced to expect additional diagnostic information provided by this feature.

Comprehensive testing requires crafting a number of tests (each being a specialized classfile) which triggers a VerifyError in each possible place in the code, as well as creating a variety of tests that exercise the different origins for types (stack/locals/constant pool).

Risks and Assumptions

Very low risk. We do assume that no one is dependent on the existing contents of the VerifyError exception message and thus it is safe for us to augment it without compatibility problems. If this assumption is wrong we may want to investigate the listed alternative.

Dependences

No dependencies

Impact

We expect no impact upon other parts of the platform.