Grails 8 Upgrade Guide

<!--
SPDX-License-Identifier: Apache-2.0

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements; and to You under the Apache License, Version 2.0.
-->

What I Do

• Guide upgrades of Grails applications from Grails 7.x to Grails 8.
• Turn the Grails 8 upgrade guide into a practical migration checklist.
• Identify Groovy 5, Spring Boot 4.1, Spring Framework 7, Jackson 3, Gradle platform, Micronaut, Hibernate, TagLib, testing, validation, and content negotiation changes that can break an application.
• Keep migration work focused on public application behavior, not internal Grails framework implementation details.

When to Use Me

Activate this skill when:

• Updating an application to Grails 8.
• Reviewing a Grails 8 upgrade branch or pull request.
• Fixing tests, build failures, runtime failures, or behavior changes after moving from Grails 7.x to Grails 8.
• Deciding whether an upgrade should remain on Hibernate 5 or opt in to Hibernate 7.
• Updating application build files, configuration, custom Spring Boot integration, TagLibs, JSON rendering, or content negotiation behavior for Grails 8.

Primary Sources

Use the published Grails documentation as the source of truth before changing an application. The URLs below use <version>, which stands for the Grails 8 version the application is upgrading to, such as the grailsVersion in its gradle.properties; use snapshot for a snapshot version.

Do not assume https://grails.apache.org/docs/latest/ points at Grails 8. Check the version printed on the snapshot documentation too: snapshot can track a newer development branch. When testing a local 8.0.x checkout, compare its grails-doc/src/en/guide/upgrading/upgrading80x.adoc and dependencies.gradle with the published guide before applying guidance from a later branch.

Upgrade Baseline

Start every Grails 8 upgrade by checking these platform requirements:

• Use JDK 21 or later to build and run ordinary Grails 8 applications.
• Use JDK 25 or later if the application uses grails-micronaut, micronaut-http-client, or other Micronaut features.
• Update the Gradle wrapper to the Grails 8 managed line, currently Gradle 9.8.0. The Grails 8 Gradle plugins require Gradle 9.7 or later.
• Expect Spring Boot 4.1.x, Spring Framework 7.0.x, Spring Security 7.1.x, Spring Data 2026.0.x, Micrometer 1.17.x, Jackson 3.1.x, Tomcat 11.0.x, and Jakarta Servlet 6.1.
• Keep using jakarta.* APIs. Do not reintroduce javax.* packages.
• Add runtimeOnly 'org.springframework.boot:spring-boot-properties-migrator' temporarily during the migration, boot once, fix reported configuration properties, then remove it.

Migration Workflow

Use this order so failures are isolated and reversible:

1. Move the build, CI, and deployment runtime to the required JDK.
2. Update the Grails version and apply the verified dependency, build and configuration changes below, checking the target version's guide and BOM.
3. Boot with the Spring Boot properties migrator and fix configuration warnings.
4. Fix dependency management and starter changes before code changes.
5. Compile and fix direct Spring Boot, Spring Framework, Jackson, Hibernate, and testing API removals.
6. Run application tests and manually exercise public behavior that depends on rendering, validation, content negotiation, persistence, and custom Spring integration.
7. Remove temporary migration dependencies and compatibility toggles once the application is clean.

For large applications, batch syntax-only checks across source files with the target Groovy compiler before repeatedly compiling the whole application. A build can stop at the first parser failure even when dozens of files share it. Parsing is a diagnostic step, not a substitute for compilation or tests.

Before compensating for an apparent framework/compiler regression, reproduce the same public behavior on both the old and target stacks with neutral fixtures. Distinguish an intentional migration, a pre-existing assumption exposed by the upgrade, and a pre-release defect. For overload or proxy failures, compare concrete instances with proxies and inspect the compiled call target; an Object fallback does not by itself prove that runtime type matching is broken. Prefer a framework fix for a confirmed regression, and document narrowly scoped application workarounds beside the code.

Build and Dependency Management

Verified Generated-Application Differences

The following differences were verified against Grails Forge-generated 7.2.4 and 8.0.0-SNAPSHOT web applications, both using Hibernate 5 and Undertow. The Grails 8 baseline selected logback-config to make its optional logging file explicit. These are generated defaults; retain deliberate application customizations where they remain supported.

Native Dependency Management

Grails 8 no longer applies the io.spring.dependency-management plugin by default.

• Grails now uses Gradle native platform() dependency management with the Grails BOM.
• The Grails Gradle Plugin auto-applies the selected Grails BOM to declarable configurations.
• Existing version overrides in gradle.properties and ext['property.version'] still work through the bundled org.apache.grails.gradle.bom-property-overrides plugin.
• Grails BOMs now follow the upstream BOM property names: an override of a version Spring Boot also manages uses Spring Boot's property name, and for a module Spring Boot manages through an imported BOM, the property Spring Boot imports that BOM with. Rename Grails-specific overrides, because a property no BOM declares is silently ignored:

• Replace grails { springDependencyManagement = false } with grails { bom = null } for new builds that intentionally opt out.
• If Spring DM was used to pin arbitrary dependencies, replace it with direct dependencies or Gradle resolutionStrategy.force where a transitive version must be forced.
• If strict BOM behavior is required, explicitly use enforcedPlatform("org.apache.grails:grails-bom:$grailsVersion").
• Check requested and selected versions with dependencyInsight on the configuration that actually supplies the failing code. A direct dependency version is not a force: a BOM can select a newer version, and browser-test, runtime, asset-development, and build-plugin configurations can select different versions. Keep application version properties consistent with the verified BOM baseline or deliberate newer overrides; do not infer the loaded jQuery or other library version from gradle.properties alone.

For builds with buildSrc or an included build-logic project:

• Use org.apache.grails:grails-gradle-bom for the Gradle plugin classpath. Gradle 9 embeds Groovy 4, while the application BOM manages Groovy 5; do not import the application runtime stack into convention-plugin compilation.
• Keep application plugins such as database migration on the application's dependencies. Grails 8 provisions their CLI companions; they do not belong on the convention-plugin classpath just to expose commands.
• Audit third-party Gradle plugins for Gradle 9 support. For example, JRebel Gradle plugin 1.2.1 calls the removed org.gradle.util.ConfigureUtil; 1.2.3 works with the Gradle 9 build configuration.
• For a local framework build, publish both the Grails Gradle plugins and framework artifacts. The root publishAllToMavenLocal task also publishes Forge in order. Enable Maven Local separately for plugin management, application dependency resolution, and any included build's repositories.
• grails-gradle-plugins transitively resolves the Grails publish plugin even when no publishing task runs. A pre-release framework checkout may require ASF staging for that dependency; use a repository content filter and make this local-validation setup explicit.
• Replace org.apache.grails.data:grails-datamapping-async with org.apache.grails:grails-datamapping-async. Remove an old unversioned org.fusesource.jansi:jansi runtime dependency if it was only inherited from generated Grails 7 build files; it is no longer managed for application runtime.
• Remove matching <withJansi>true</withJansi> directives from every profile in custom Logback configuration, including custom ConsoleAppender subclasses. Otherwise Logback still tries to load org.fusesource.jansi.AnsiConsole and warns before falling back to the ordinary stream. Grails 8's generated logging configuration uses Spring Boot's console defaults without Jansi; native ANSI output can still use Boot's %clr converter. Jansi's global stream replacement can also break logging after a DevTools restart (Grails issue #15663).

Spring Boot 4 renamed common starters:

For WAR deployment to an external servlet container, replace providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat' with providedRuntime 'org.springframework.boot:spring-boot-starter-tomcat-runtime'.

Spring Boot 4 dropped spring-boot-starter-undertow; Grails 8 provides Undertow through the Grails Undertow plugin instead. For an application that runs on Undertow, make the build match what Grails Forge generates for --servlet=undertow:

• Replace spring-boot-starter-undertow with implementation 'org.apache.grails:grails-undertow', without a version; the Grails BOM manages it.
• Remove direct io.undertow:undertow-servlet and io.undertow:undertow-websockets-jsr dependencies from the old stack. Servlet 6.1 support uses Undertow core 2.4.x with servlet/websocket artifacts in io.undertow.ee; let the Grails Undertow plugin and BOM supply the compatible set.
• Do not declare spring-boot-starter-tomcat or spring-boot-tomcat; those are what Forge adds for Tomcat applications instead.
• Keep the server.undertow.* properties; they continue to work. server.undertow.max-http-post-size now defaults to 2MB, Undertow's hardened default; set it to -1 only if the application relied on the previous unlimited request size.

Spring Retry is no longer managed by Spring Boot. If the application directly uses its RetryTemplate, @Retryable, @EnableRetry, or @Recover, declare org.springframework.retry:spring-retry directly. The Grails 8 BOM manages its version; otherwise supply an explicit version or migrate to Spring Framework's retry API. A transitive dependency is not a declaration of the application's own use.

Split Auto-Configuration Modules

• Inventory the technologies the application actually uses and inspect each application's resolved runtime graph. Having the third-party library no longer guarantees Boot auto-configuration is present: Spring Session needs spring-boot-session, Spring Integration needs spring-boot-integration, and JSON mapping needs spring-boot-jackson (or their appropriate starters). Check actual beans and behavior after adding a module; successful compilation cannot detect missing auto-configuration.
• Distinguish Boot-managed infrastructure from application/Grails-owned configuration. Do not add Boot Liquibase or Batch auto-configuration merely because those libraries are present when the Grails migration plugin or an explicit JDBC Batch configuration already owns their lifecycle. Use technology-specific test starters when relying on their Boot test integration.
• Trace deprecated starters to their declaring dependency before changing them. A renamed application dependency does not remove an old starter brought in by a plugin; avoid excluding its supporting modules without verifying the replacement graph.
• Keep the properties migrator until the deployed/development configuration, including private external overrides, has been exercised. A clean TEST startup does not certify those branches. Record the removal follow-up if deployed verification is still pending.

Spring Session Cookies, Filters, and Stored Sessions

• Verify both native-container and Spring Session cookies. Missing Boot session auto-configuration can make the fallback cookie serializer adopt JSESSIONID instead of SESSION; decoding a native cookie as a Base64 session ID can send binary/NUL bytes to a JDBC lookup. A database error on the session-ID query parameter is not proof of corrupt stored attributes. Test a native cookie, a valid Spring Session cookie, and a cookie-free first request.
• Adding the missing session module also introduces Boot's filter registration. Remove a duplicate application registration and preserve its ordering through spring.session.servlet.filter-order. Audit dispatcher types too: an ERROR dispatch can re-enter Spring Session despite an API filter marking the request as already filtered. Where the application deliberately excludes error dispatches, configure spring.session.servlet.filter-dispatcher-types=REQUEST,ASYNC and test real API error responses. A comma-separated scalar worked with the checked Grails 8 configuration; a Groovy list of strings bound without converting its elements to Boot's dispatcher enum.
• Audit serialized session attributes independently of cookie handling. Changed framework token-holder serialization can make pre-upgrade sessions unreadable. When compatible restoration is not possible, invalidate sessions once during deployment, deleting child attributes before parent sessions, and communicate reauthentication. Do not reset sessions on every startup or assume pinning an old serial UID makes incompatible state compatible.

Spring Boot 4 and Spring Framework 7 Code Changes

Check for direct imports or references to Spring Boot auto-configuration classes. Spring Boot 4 split the old monolithic auto-configure module into domain modules, and many classes moved.

Check both the package and the supplying module rather than guessing package renames. FilterRegistrationBean and ServletContextInitializer remain in org.springframework.boot.web.servlet. DataSourceHealthIndicator moves to org.springframework.boot.jdbc.health and needs an explicit spring-boot-jdbc dependency when application code references it. For an optional auto-configuration used only in an exclusion, @EnableAutoConfiguration(excludeName = ['org.springframework.boot.ldap.autoconfigure.LdapAutoConfiguration']) avoids adding a module just to reference its class.

Examples:

// Before
import org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration

// After
import org.springframework.boot.mongodb.autoconfigure.MongoAutoConfiguration

If the application contributes an EnvironmentPostProcessor, update both imports and META-INF/spring.factories keys from org.springframework.boot.env.EnvironmentPostProcessor to org.springframework.boot.EnvironmentPostProcessor.

Other common Spring changes:

• Rename HttpStatus.MOVED_TEMPORARILY to HttpStatus.FOUND.
• Compare a servlet response's integer status with HttpStatus.UNPROCESSABLE_ENTITY.value() rather than the HttpStatus object. Keep numeric wire assertions separate from typed client-response status assertions.
• Remove HandlerAdapter.getLastModified overrides.
• Replace use of removed Spring theme infrastructure such as ThemeSource, Theme, SimpleTheme, and SessionThemeResolver.
• Replace SecurityProperties.DEFAULT_FILTER_ORDER with -100 only when a direct constant replacement is needed, and prefer fluent HttpSecurity configuration long term.
• Update embedded server imports such as TomcatServletWebServerFactory to the new Spring Boot 4 packages.
• Add spring-boot-tomcat explicitly if application code directly references Tomcat classes.
• Prefer JSpecify nullability annotations for new Spring-facing code.
• Replace the removed one-argument ContentCachingRequestWrapper constructor with the request and an explicit cache limit. A limit of 0 preserves the former unlimited behavior; choose a finite limit only with deliberate handling of truncated cached bodies.
• Spring Messaging 7 adds default-destination overloads such as convertAndSend(Object payload, Map headers). A Groovy call convertAndSend(topic, mapPayload) can select this instead of the destination/payload overload, producing No 'defaultDestination' configured or silently sending the topic string as payload to an unrelated configured default. Cast the map argument explicitly: convertAndSend(topic, (Object) mapPayload). Verify the destination and payload with a real SimpMessagingTemplate and message channel, both with and without a default destination; mocks alone can hide the overload mismatch.

Groovy 5 Source Compatibility

Syntax, Conversions, and Groovy Truth

• Remove a trailing comma after the last enum constant when fields or methods follow it. A newline is sufficient; adding a semicolon is unnecessary in Groovy. Check nested enums and constants followed by comments too.
• Replace value instanceof List<MyType> with value instanceof List (or an unbounded wildcard). The runtime check never verified element types. If static compilation needs the generic type afterwards, keep it in an explicit cast or typed local variable.
• Audit value as boolean when value can be null: Groovy 5 can throw IllegalArgumentException: null to boolean. Use value != null for presence checks or !!value for Groovy truth, preserving empty collection/string and zero semantics where relevant.
• Make map-key and filesystem assertions explicit. Use map.get(key) / containsKey(key) when testing entries such as metaClass, rather than bean-property introspection. Groovy 5 File/Path truth can test filesystem existence; use path != null when asserting that a path was supplied, and an explicit existence check when that is the contract.
• Use a collection copy constructor such as new LinkedHashSet<Element>(source) when a shallow copy is intended and a runtime collection's clone() is inaccessible. Do not rely on reflective access to a protected implementation method.

Class Names, Properties, and DSL Scope

• Investigate repeated getter frames in a StackOverflowError before changing the query. An acronym getter such as getURLValue(LocalDate asOf = LocalDate.now()) also exposes a zero-argument getter and the case-sensitive property URLValue. In the checked Groovy 5 stack, URLValue.lookup() inside that getter resolved the property and re-entered the getter instead of selecting the class; the same plain-Groovy example worked on the Groovy 4 stack. Qualify the class (example.URLValue.lookup()) and comment why the qualification prevents recursion. This is not specific to GORM or Hibernate proxies.
• Qualify domain constants and reusable validator closures inside static constraints, for example matches: Book.CODE_PATTERN or validator: Book.codeValidator. Under Groovy 5, unqualified names can resolve against the mapping DSL delegate instead of the declaring class and fail during datastore initialization.
• Keep closures declared locally inside static constraints as local references; qualifying those as class members introduces a missing-property error. Apply the same ownership check to static helpers called from binding/validation closures: qualify the declaring class when lookup is hitting the wrong owner or delegate.
• ConfigObject.properties is a read-only bean property in Groovy 5. For datasource or Quartz configuration whose actual key is properties, construct a map and use put('properties', values) or putAll([properties: values]); do not assign delegate.properties in a configuration closure.

The following generic example was compared using the Grails 7.2.4 / Groovy 4 and Grails 8 snapshot / Groovy 5.1.3 stacks. It has no GORM domain, database, or proxy:

package example

import java.time.LocalDate

class URLValue {
    static URLValue lookup() { new URLValue() }
}

class ReferenceHolder {
    URLValue getURLValue(LocalDate asOf = LocalDate.now()) {
        // Qualify the class to avoid resolving the URLValue property and recursively calling this getter.
        example.URLValue.lookup()
    }
}

The return type is a type reference; the receiver of the method call is where the ambiguity occurs. For a domain query, the same diagnosis applies to URLValue.createCriteria(). Qualify only the ambiguous receiver, preserve the query, and verify against the actual compiler version before treating the workaround as permanent.

Closure Logger Access

• Separate access to a class's own @Slf4j logger from logger inheritance. A returned closure from a Spring-enhanced @Configuration class failed with MissingPropertyException: log naming the generated CGLIB subclass, despite the declaring class having @Slf4j. Qualifying ClientConfiguration.log inside that closure selects the same logger generated on ClientConfiguration; it does not introduce a superclass logger. Verify the actual proxied bean and callback; a directly constructed configuration instance may not reproduce the failure.
• For genuinely inherited logger use, the default private @Slf4j field is a separate visibility concern. If subclasses intentionally share it, configure protected visibility on the base logger with @Slf4j(visibilityId = 'logger') and @VisibilityOptions(id = 'logger', value = Visibility.PROTECTED); if a base-class closure should use the base logger, qualify that declaring class. Preserve intentional logger categories rather than adding duplicate logging annotations mechanically. Remove unused logging annotations from interfaces, where their generated private field is invalid.

import groovy.util.logging.Slf4j
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Slf4j
@Configuration
class ClientConfiguration {
    @Bean
    Runnable clientCallback() {
        return () -> {
            // Use this configuration class's logger rather than looking up log on the CGLIB subclass.
            ClientConfiguration.log.debug('Configuring client')
        }
    }
}

These are targeted receiver/visibility fixes, not a general requirement to replace log everywhere in Groovy 5. The CGLIB case was verified in the application stack but has not been isolated to a particular compiler commit. Do not attribute it to the overload-dispatch change below without a separate reproducer.

Runtime Overload Dispatch

• Groovy 5's nestmate/direct-call change, GROOVY-10687 removed reflective dispatch used for some non-public calls inside closures. In the checked Groovy 4 stack, a protected overloaded method in a closure could be reselected using the runtime argument type, even under static compilation; Groovy 5 invokes the statically selected overload directly. This can surface through transactional services.
• A static caller that only knows BaseMessage cannot select an overload accepting a particular subclass. <T extends BaseMessage> still exposes the base type to static selection and did not fix the compared example. The compiler is not generally preferring the least-specific runtime type; Groovy 4's second, reflective dispatch had concealed the distinction.

This comparison used both plain @CompileStatic classes and transactional services, without Hibernate proxies:

If the application's contract is runtime overload selection, mark only that dispatch boundary dynamic:

import groovy.transform.CompileDynamic

@CompileDynamic
String dispatch(BaseMessage message) {
    handler.process(message)
}

Keep the typed overload implementations statically compiled and retain process(Object unsupported) as the unsupported-type guard. Do not replace the guard with an instanceof router before identifying the changed dispatch. Compare concrete instances with proxies separately: runtime dispatch does not itself unwrap a base-class Hibernate proxy. Verify every supported subtype and the unsupported-type path through public entrypoints.

Static Compilation and Version-Specific Compiler Workarounds

• Groovy 5 can infer Object where earlier versions accepted a more specific type. Prefer typed locals across try/catch and Map.get(null) over ambiguous null-key subscript expressions; do not disable static checking broadly.
• If a nested ternary selecting class literals produces a cast of a Class object to one of the represented domain types, inspect the generated code. Explicit Class<?> locals with if/else assignments fixed the checked application case. Treat this as a targeted compiler workaround, not a reason to replace every ternary.
• In the checked Groovy 5.1.3 / Grails 8 snapshot, a typed local named first in transactional code contaminated the generated setTargetDatastore method's inferred type, producing a cast of the datastore to an unrelated application class. Confirm the generated bytecode and use a descriptive local name as a narrowly scoped workaround; do not change datastore wiring to satisfy that cast. Recheck the framework/compiler fix before generalizing this snapshot defect.
• GROOVY-12437 is a confirmed separate-compilation defect affecting ternary expressions selecting inherited generic map properties under @CompileStatic: compiling the superclass and subclass together succeeds, but compiling the subclass against superclass bytecode reports unable to resolve class E at line -1. The standalone reproducer passes on Groovy 4.0.33 and fails on 5.0.8, 5.1.2, and 5.1.3, including JDK 21 and 25 for 5.1.3. Replace the affected ternary with if/else assignments explicitly cast to the concrete map type, and reference the issue beside that code. This localized workaround allows GroovyCompile.options.incremental = true. Verify with a clean --no-build-cache --rerun-tasks build, followed by a source edit and an incremental --no-build-cache --info build without --rerun-tasks; also compile the subclass alone against superclass bytecode to isolate the reported defect. Disabling incremental compilation is a fallback if affected code cannot be localized. Check the issue's fix version before removing the source workaround. Do not call it a Gradle defect solely because an incremental build exposes it.

Configuration Changes

Review application configuration after booting with the Spring Boot properties migrator.

• Rename Spring Boot MongoDB auto-configuration properties from spring.data.mongodb.* to spring.mongodb.*.
• Do not change Grails GORM MongoDB mongodb.* properties for this Spring Boot rename.
• Jackson configuration under spring.jackson.* was reorganized. Watch for migrator output such as spring.jackson.read.* moving to spring.jackson.json.read.* and spring.jackson.write.* moving to spring.jackson.json.write.*.
• DevTools live reload is disabled by default. Set spring.devtools.livereload.enabled: true under the development environment if needed.
• Spring Boot now writes build info to META-INF/build-info.properties by default.
• Liveness and readiness probes are enabled by default on the health endpoint. Disable through management.endpoint.health.probes.enabled: false only if required.
• If grails.mail.overrideAddress is set, it now also replaces a from set in sendMail. To keep the application's sender while still redirecting every recipient, use grails.mail.overrideToAddress in its place.
• Replace every grails.controllers.upload.* property with its spring.servlet.multipart.* equivalent. Grails 8 rejects the old namespace at startup. Set explicit per-file and per-request limits to preserve existing uploads, and check the servlet container's overall request limit as well. An unspecified multipart location now uses the container's temporary directory.
• Plugin message bundles must use the plugin's namespace: a plugin named common ships common.properties or common-<purpose>.properties, with matching locale variants. Rename generic plugin bundles such as messages.properties; generateI18nDescriptor rejects colliding names. Application bundles still use the application message-source conventions.
• Boot now owns the ResourceBundleMessageSource; application calls to old Grails-specific methods such as getMergedPluginProperties fail. For a known code catalog, enumerate its namespaced ResourceBundle keys and resolve the text through the public MessageSource API so application overrides remain effective. Test catalog/search and validation-error paths as well as individual message lookups.
• If Liquibase includeAll encounters compiled script/closure .class files beside Groovy changelogs, restrict discovery with endsWithFilter: '.groovy'. Verify existing source changelogs are still discovered; do not alter already-applied changesets to suppress resource warnings.
• Preserve explicit metadata keys with Metadata.current.getProperty('info.app.name', String, null) and getProperty('info.app.version', String, null) rather than subscripting Metadata. The convenience getters getApplicationName() and getApplicationVersion() read those same keys; applicationName and applicationVersion are their Groovy bean-property spellings, not different configuration keys. The name getter supplies grailsApplication as its default, and the version getter supplies null.
• Audit external and gitignored configuration loaded through grails.config.locations, including development-only blocks and home-directory overrides. A ConfigSlurper stack trace naming a generated Script_... class can originate there; test-environment startup does not exercise those branches. Replace remaining Metadata.current['info.app.name'] and grailsApplication.metadata['info.app.version'] lookups with their typed accessors, and keep private local configuration out of commits.
• Move spring.http.client.connect-timeout and read-timeout to spring.http.clients.*, and spring.http.client.factory to spring.http.clients.imperative.factory in Boot 4.1. Preserve the chosen HTTP implementation and existing timeout values.
• Replace management.endpoints.enabled-by-default with management.endpoints.access.default (none or unrestricted as appropriate), and per-endpoint enabled flags with access levels. Check web exposure independently, because accessibility and exposure are separate settings.
• Replace server.maxHttpHeaderSize / server.max-http-header-size with server.max-http-request-header-size and an explicit data size, such as 128KB. Reconcile duplicate old/new declarations so the effective request-header limit is retained.

Micronaut Integration

Micronaut-enabled Grails 8 applications have stricter requirements than ordinary Grails 8 applications.

• Run Micronaut-enabled applications on JDK 25 or later.
• Apply a Micronaut-compatible Grails BOM as enforcedPlatform, not plain platform.
• Use grails-micronaut-bom for the default Micronaut setup.
• Use grails-hibernate5-micronaut-bom for Micronaut with Hibernate 5.
• Use grails-hibernate7-micronaut-bom for Micronaut with Hibernate 7.
• Remove explicit BootArchive.loaderImplementation = LoaderImplementation.CLASSIC; Spring Boot 4 removed the CLASSIC loader.
• Do not disable grails { micronautAutoSetup = false } unless the build intentionally owns all Micronaut annotation processors and BOM validation.

Example:

dependencies {
    implementation enforcedPlatform("org.apache.grails:grails-micronaut-bom:$grailsVersion")
    implementation 'org.apache.grails:grails-micronaut'
}

Jackson and JSON Rendering

Grails 8 follows Spring Boot 4 and Jackson 3.

• Jackson annotations remain under com.fasterxml.jackson.annotation.*.
• Jackson databind moves from com.fasterxml.jackson.databind.* to tools.jackson.databind.*.
• The auto-configured mapper is tools.jackson.databind.json.JsonMapper, not Jackson 2 ObjectMapper.
• Prefer JsonMapper.builder().build() for direct mapper construction.
• Jackson 3 exceptions are unchecked JacksonException types.
• Default dates are ISO-8601 strings instead of numeric timestamps.
• To keep Jackson 2 defaults temporarily, set spring.jackson.use-jackson2-defaults: true.

For custom mapper configurations:

• Declare bean return types as JsonMapper, retaining bean names/qualifiers and the intended primary bean. An ObjectMapper return type may not suppress Boot's format-specific default. Verify the real application context, not only test mapper replacements. Custom builders can use configureForJackson2() to preserve published defaults while running Jackson 3; Boot properties do not configure manually constructed mappers.
• Move custom serializers/deserializers to ValueSerializer, ValueDeserializer, and SerializationContext; modifiers use ValueSerializerModifier / ValueDeserializerModifier with BeanDescription.Supplier. Configure mix-ins on the builder before building the immutable mapper, including MixInResolver.hasMixIns() and snapshot() for custom resolvers. Jackson 3 includes java.time support; retain only required date-format overrides. Migrate databind annotations such as JsonSerialize, while retaining shared Jackson annotations.
• Preserve wire behavior explicitly: null inclusion, enum representation, plain decimals, unknown properties, compact/pretty output, date precision, local wall-clock versus offset timestamps, and +00:00 versus Z. Exercise form authentication, JSON, multipart and binary HTTP paths. In Spring 7, RestClient.Builder.configureMessageConverters starts with an empty builder: call registerDefaults() before editing its converter list, then use JacksonJsonHttpMessageConverter; otherwise even String form bodies can lose their converter.
• Distinguish migrating application JSON from eliminating Jackson 2 jars. Trace non-constraint dependency edges, excluding shared jackson-annotations, and check actual replacement releases. Libraries compiled against Jackson 2 cannot use Jackson 3 through exclusions or version substitution. Also search legacy wrapper classes such as Batch's Jackson2ExecutionContextStringSerializer: changing persisted execution-context JSON requires compatibility tests against existing rows, not just a new-serializer round trip.

Spring Boot helper renames include:

JSON views now use groovy.json.JsonGenerator. If custom JSON view converters used Grails-specific generator classes, migrate them to groovy.json.JsonGenerator.Converter and rename the service loader file to src/main/resources/META-INF/services/groovy.json.JsonGenerator$Converter.

Enum serialization changed:

• SimpleEnumMarshaller is the default for JSON and XML enum serialization.
• Remove explicit configuration that opted into simple enum formatting.
• Rendering a single enum with render(MyEnum.VALUE as JSON) now throws ConverterException; render an object, map, or explicit string instead.

OpenAPI Documentation

For an application using Swagger/JAX-RS scanning solely to document Grails controllers, adopt implementation 'org.apache.grails:grails-openapi' and retain its standard @Operation, @ApiResponse, @Parameter, and @Schema annotations. See the target version's OpenAPI guide, checking the branch as described above.

• The module supplies the generateOpenApi Gradle task through its auto-provisioned CLI companion. Use that task; do not recreate it or write a custom document generator. Remove the old Swagger Gradle plugin, its buildscript dependency, JAX-RS scanner and documentation-only JAX-RS annotations.
• Configure grails.openapi.base-document to retain the existing title, servers, security schemes, tag descriptions and viewer extensions. Use annotated-only and paths-to-match to retain the intended public API selection.
• Paths now come from Grails URL mappings, not @Path. Reconcile base-document server prefixes so /api/v1 is not duplicated, and rename @Parameter(in = PATH) declarations to match actual mapping variables. Verify non-GET operations against the mappings.
• Groovy metaClass and validateable errors properties are already excluded; remove a custom model converter whose only purpose was hiding those properties.
• Generation starts an application context and needs its datasource and services. Configure the supplied task and CLI classpath for a disposable build environment when packaging must work without an external database. CLI-only dependencies belong in grailsCli, not the deployed runtime.
• Generate into build/openapi, then include the output when packaging or running the application. Do not put generated documentation into sourceSets.main.output or make processResources depend on generation: the command itself needs classes, creating a dependency cycle.
• For a static Redoc page, continue serving the generated YAML through the application's existing endpoint. Add springdoc only if runtime /v3/api-docs or Swagger UI is wanted. Test the generated contract, schema references, and the served document, not just task success.

Hibernate and GORM

Do not assume a Grails 8 upgrade requires Hibernate 7.

• Grails 8 supports Hibernate 5 by default.
• Opt in to Hibernate 7 only when the application is ready for Hibernate ORM 7 changes.
• If application code directly imports Spring ORM Hibernate classes, replace org.springframework.orm.hibernate5 with org.grails.orm.hibernate.support.hibernate5 for Hibernate 5 or org.grails.orm.hibernate.support.hibernate7 for Hibernate 7.

Hibernate 7 opt-in example:

dependencies {
    implementation enforcedPlatform("org.apache.grails:grails-hibernate7-bom:$grailsVersion")
    implementation 'org.apache.grails:grails-hibernate7'
}

If moving from Hibernate 5 to Hibernate 7, audit direct Hibernate API use:

Also check for:

• Removed annotations such as @Where, @WhereJoinTable, @Proxy, @LazyCollection, @Persister, @SelectBeforeUpdate, and @Loader.
• Removed CascadeType.SAVE_UPDATE; use CascadeType.ALL, CascadeType.PERSIST, or CascadeType.MERGE as appropriate.
• Detached refresh() or lock() calls, which now throw IllegalArgumentException.
• Native SQL query results now returning java.time date/time types instead of java.sql date/time types.
• StatelessSession participating in second-level cache by default. Set CacheMode.IGNORE for intentional cache bypass.
• DDL differences for character columns, Oracle floating and timestamp columns, SQL Server timestamp precision, and MySQL or MariaDB array columns.
• Hibernate 6 intermediate changes: HQL join result typing, 1-based ordinal parameters, legacy Criteria API removal, boolean type mapping converters, and continued jakarta.persistence usage.

GORM behavior changes:

• Unconstrained persistent domain properties are nullable by default in Grails 8.
• Declare nullable: false on required domain properties, or set grails.gorm.default.nullable: false to restore the previous application-wide default.
• Command object fields are unaffected and remain required by default.
• Check command objects that import domain constraints too: making an existing domain field explicitly required can also restore the intended requiredness of an imported constraint. Verify both domain and command validation rather than changing the application's global nullability setting to satisfy one fixture.
• GORM dynamic methods such as save(), delete(), get(), load(), and merge() are not affected by Hibernate Session API removals.
• Migrate affected legacy namedQueries definitions and createNamedQuery calls to supported where / DetachedCriteria queries. Grails 8 removed deprecated query infrastructure; an old generated method name is not proof the underlying API remains supported. Retain every predicate and verify excluded, unrelated, and absent rows.
• The sort and order arguments of list(), dynamic finders, where queries, criteria queries and listOrderBy* are validated on both Hibernate versions: sort must be a dotted property path that resolves through the mapping (a dotted alias such as c.name is still passed through), and order must be asc or desc. Anything else throws IllegalArgumentException (Invalid sort property / Invalid sort direction) instead of being ignored or failing inside Hibernate. On Hibernate 7, list() also rejects a fetch key that is not a persistent property.
• A GString coerced to String before executeQuery or another checked GORM query method can fail compilation with GormUnsafeQueryString. Bind data values as parameters. When interpolation is solely for reviewed, fixed query fragments and values already use named parameters, document that distinction and suppress the check on that specific method rather than converting query syntax into bound values.
• Check single-result criteria explicitly. In the tested pre-release Grails 8 build, withCriteria(uniqueResult: true) returned a PagedResultList; Grails 7 dispatched it to get. Use createCriteria().get { ... } for entity/scalar results, preserving cache and valid fetch joins in the DSL. Test both absent and present results, especially row-count projections where a nonempty list containing zero is truthy. Treat this as a version-specific regression, not a universal documented removal.
• Nested transaction propagation was corrected in Grails commit bd268672976: REQUIRED joins an active transaction, while REQUIRES_NEW suspends it and uses a separate session, then restores the outer session. This also affects SimpleMap-backed domain/service unit tests. A thread-bound test session does not mean every service invocation shares one transaction or first-level cache; check the service annotations and explicit withNewTransaction calls before attributing changed fixture visibility to a regression.
• Verify ident() and reload/proxy behavior for composite keys and renamed single-property identifiers. In the checked pre-release build, ident() read only the ordinary id property, returning null for a persisted composite-key domain and for a key mapped with id name: 'code'; Grails 7 used the mapped property or constructed a serializable identifier from the composite key fields. Consequently load(entity.ident()) returned null before any proxy was created. Regression tests reproduced both cases on Hibernate 5 and Hibernate 7. Treat this as a framework regression to isolate and fix, rather than excluding composite-key domains from coverage or interpreting the null as a proxy-initialization change.
• Initialization does not change a Hibernate base-class proxy into its concrete subtype. Before subclass/trait-only access, unwrap through the supported Hibernate API and retain the resulting instance; a cast alone is not unwrapping. A collection find still returns the original element even if its predicate unwrapped it; use findResult when the intended result is the unwrapped matching object. Equivalent warmed-call-site failures were reproduced on the old stack too, so distinguish a pre-existing proxy assumption from a new compiler regression.