After upgrading jOOQ's Gradle codegen plugin, compilation fails on REQUIRE_RUNTIME_JOOQ_VERSION in the generated DefaultCatalog; what went wrong and how do you fix it?
answer
- generator newer than runtime
- one constant per minor release
- a BOM pins the runtime
- align versions, don't silence
basics
~20 sjOOQ's generated catalog references a constant for the generator's minor release, such as Constants.VERSION_3_21, so it stops compiling when the runtime jar is an older minor. Align the plugin and runtime versions instead of disabling the check.
solid answer
~40 sWith `jooqVersionReference` at its default of `true`, the generator writes `REQUIRE_RUNTIME_JOOQ_VERSION = Constants.VERSION_3_21` into `DefaultCatalog`; an older runtime has no such constant, so the build breaks at compile time rather than with a linkage error at run time. The usual cause is two version sources: the plugin declared as `id("org.jooq.jooq-codegen-gradle") version "..."` while Spring Boot's dependency management pins the runtime, at 3.21.7 in Boot 4.1.1. Fix it by pinning the plugin to the runtime's version, or by raising the managed runtime to the plugin's, and keep extensions on the `jooqCodegen` classpath at that same version. Setting `jooqVersionReference` to `false` only hides the mismatch.
code
kotlin · 10 linesplugins {
id("org.jooq.jooq-codegen-gradle") version "3.21.7"
}
val jooqVersion = "3.21.7"
dependencies {
implementation("org.jooq:jooq:$jooqVersion")
jooqCodegen("org.jooq:jooq-meta-extensions:$jooqVersion")
}go deeper
Recall that jOOQ's generator and runtime are separate artifacts and that their versions must match.
Explain the REQUIRE_RUNTIME_JOOQ_VERSION field: it references the generator's minor-release constant, so an older runtime fails compilation.
Trace the mismatch to its two version sources, a plugin version and a Boot-managed runtime, and fix the source instead of disabling the reference.
Make the jOOQ version one number per build and upgrade the plugin with the platform BOM, so generated code and runtime never drift apart.
## What the failing line is Every run of jOOQ's code generator writes a catalog class, `DefaultCatalog` under the default naming strategy. When the `<generate>` flag **`jooqVersionReference`** is `true`, which is its default, the Java generator adds one field to it: ```java private static final String REQUIRE_RUNTIME_JOOQ_VERSION = Constants.VERSION_3_21; ``` `Constants` is `org.jooq.Constants` from the **runtime** jar, and `VERSION_3_21` names the **generator's** minor release. The generated Javadoc above the field states the intent: if it does not compile, the runtime library is an older minor release than the generator. A 3.21 generator paired with a runtime that predates 3.21 cannot resolve the constant, and compilation stops on this line. ## Why jOOQ fails the compile on purpose Generated code calls the runtime API of the release that generated it. Against an older runtime some of those calls may not exist, which would surface as `NoSuchMethodError` or similar linkage errors only when a particular code path runs, possibly in production. The version reference moves the failure to the first compile, where it is cheap to fix. The guard is one-sided: - **Runtime older than the generator's minor**: the constant is missing, so compilation fails. - **Runtime of the same minor** (generator 3.21.9, runtime 3.21.7): compiles. - **Runtime newer than the generator**: compiles as long as the newer `Constants` still carries that constant. ## Where the two versions come from A typical Gradle build has two independent version sources: 1. **The plugin**: `id("org.jooq.jooq-codegen-gradle") version "..."`. The plugin brings its own `jooq-codegen` (and with it `jooq-meta` and `jooq`) at that version; that is the generator. 2. **The runtime**: `org.jooq:jooq` on the compile classpath, very often without a version because Spring Boot's dependency management supplies one. Spring Boot 4.1.1 manages jOOQ **3.21.7**. Upgrade the plugin to a newer minor while Boot still manages an older runtime, and the generated catalog asks for a constant the runtime lacks. Maven builds that inherit Spring Boot's parent are at less risk, because Boot's dependency management also lists the `jooq-codegen-maven` plugin, so plugin and runtime versions follow the same Boot release. ## Diagnosing it in practice 1. Read the compiler error: it points at `REQUIRE_RUNTIME_JOOQ_VERSION` in the generated catalog and names the missing `VERSION_` constant, which tells you the generator's minor release. 2. Ask the build which runtime it resolved: Gradle's `dependencyInsight` for `org.jooq:jooq` on the compile classpath shows the version and who chose it, often a platform BOM. 3. Compare that with the plugin version in the `plugins` block. Two different minors confirm the diagnosis; regenerating alone will not help, because the generator will write the same reference again. ## How to fix it Pick one jOOQ version and make every jOOQ artifact use it: - **Pin the plugin to the runtime**: set the plugin version to the version the runtime resolves to. - **Or raise the runtime**: override the managed jOOQ version so the runtime matches the plugin, accepting that you leave Boot's tested pairing. - **Align the codegen classpath**: anything added to the `jooqCodegen` configuration, such as `jooq-meta-extensions` for `DDLDatabase`, uses the same version. What not to do: set `jooqVersionReference` to `false`. The build goes green and the mismatch moves to run time, which is exactly what the reference exists to prevent. ## The generator's own version check There is a second, separate guard. Before generating, `GenerationTool` compares the constants in `org.jooq.Constants`, `org.jooq.meta.Constants` and `org.jooq.codegen.Constants` loaded on the generator's classpath. On a mismatch it reports "Check if you're using the same versions for org.jooq ...", through `onMisconfiguration`, whose default is `FAIL`. | Check | Runs | Catches | |---|---|---| | `REQUIRE_RUNTIME_JOOQ_VERSION` | when generated code compiles | runtime older than the generator's minor | | `GenerationTool` version comparison | when the generator starts | `jooq`, `jooq-meta`, `jooq-codegen` disagreeing inside the generator | ## A rule worth keeping Treat the jOOQ version as one number per build: - Declare it once and reuse it for the plugin's `jooqCodegen` extensions and any explicit runtime dependency. - When Spring Boot manages the runtime, upgrade the plugin together with Boot, not on its own. - Review a jOOQ upgrade as a change to both generated code and runtime, since regenerating is part of the upgrade.
- Why is jOOQ's compile-time version reference better than letting an older runtime through?Generated code calls the runtime API of its own release. Against an older runtime a missing method shows up as a linkage error such as `NoSuchMethodError`, and only when that code path runs, which tests may never reach. The version reference turns that into a compile error on the first build, where the fix is a version change.
- Does jOOQ's code generator check versions on its own classpath as well?Yes. `GenerationTool` compares the constants of `org.jooq`, `org.jooq.meta` and `org.jooq.codegen` before it generates, and reports any difference through `onMisconfiguration`, which defaults to `FAIL`. That catches a generator assembled from mixed jOOQ versions; the catalog's version reference covers the separate gap between generator and runtime.
- Setting jooqVersionReference to false fixes the build for good.
- Generated jOOQ code works with any runtime version of the same major release.
- Spring Boot's dependency management also sets the Gradle codegen plugin's version.
- The error means the schema changed and the classes need regenerating.
- A newer runtime than the generator always fails the same check.
Assumes jOOQ 3.21: the generated catalog references org.jooq.Constants.VERSION_3_21, and Spring Boot 4.1.1 manages jOOQ 3.21.7.