Catching missing reflection metadata for Jackson-serialised records before release?

[jameskomo]

A native-image CLI of mine serialised every Java record in its JSON output as {}: the record was not registered for reflection, and Jackson read nothing. No exception or warning at build or run time. JVM tests passed, and so did a smoke test on the native binary that only checked exit codes. I fixed it by registering the type in reachability-metadata.json and by checking the JSON content in the release smoke test.

Is there a better way to catch this class of problem before release? The tracing agent only sees the paths the tests exercise. Is there a build-time option that warns when a type is serialised reflectively but not registered, or a recommended way to fail fast when Jackson finds no accessors on a record?

Context, if useful: https://github.com/jameskomo/docswatcher (fix in v0.3.0).

[qoxmfaktmxj]

Yes. What bit you is the default (lenient) reflection handling: calls like Class.getRecordComponents() or getDeclaredMethods() on an unregistered type don't fail, they just come back without the members, so Jackson finds no accessors and writes {}. Native Image has a stricter mode for exactly this case.

1. Build with --exact-reachability-metadata

native-image --exact-reachability-metadata ...

With this flag, missing metadata no longer degrades silently. The binary throws a MissingReflectionRegistrationError (a java.lang.Error) that names the exact element that was not registered. getRecordComponents(), getDeclaredMethods(), getDeclaredFields() and friends are all covered. See Reachability Metadata. The docs also say this mode will become the default in a future release.

Note the scoping: --exact-reachability-metadata=<pkg> applies to reflective calls made from classes in that package. Here the calls come from Jackson, so if you scope it you need to include the Jackson databind package, not only your own. The unscoped flag on the command line covers everything and is the simplest choice for a CLI.

2. Make tests fail loudly at run time

Libraries sometimes catch Throwable, which could swallow that error. Run your native smoke tests with:

./my-cli -XX:MissingRegistrationReportingMode=Exit ...

Exit prints the error with a stack trace and exits right away, even if the error was caught. Warn just logs every missing registration and keeps going, which is handy to get a full list in one run.

3. Run the real test suite as a native image

Your smoke test only checked exit codes. The GraalVM Native Build Tools plugins can compile and run your JUnit tests as a native binary (nativeTest in Gradle, -Pnative test with the Maven plugin). Combined with the two options above, any serialization path your tests cover will fail on a missing registration instead of printing {}.

The tracing agent is still useful to generate the initial reachability-metadata.json. Exact mode catches what the agent missed, as long as your tests exercise that path in the native binary.

[jameskomo]

Thank you, this was exactly the missing piece. I turned on --exact-reachability-metadata and it caught two more missing registrations straight away: a picocli mixin class holding three command-line options, and one subcommand. In the lenient build those options would most likely have been ignored without a word, the same silent failure as the {} records.

The release smoke test now runs every command with -XX:MissingRegistrationReportingMode=Exit, on each platform's own runner, so a missing registration fails the release and names what is missing. Running the JUnit suite as a native image is next.

The change, if it helps anyone else: jameskomo/docswatcher@5f02259