Helidon 27: New Core, Broken MP — Migration Guide

Helidon 27 is the first Java microservices framework release that ships on Java’s own clock — one major version per year, timed to JDK releases. That sounds like a footnote. It isn’t. Helidon SE is gone, renamed and reorganized into a framework called Helidon Core. MicroProfile support has been pulled out into a separate project with no confirmed release date. HTTP method routing is now case-sensitive. If your app works today on Helidon 3 or 4, there’s a checklist to run before you plan any upgrade.

Helidon SE Is Now Helidon Core

The rename reflects a real structural change. Helidon Core ships with two programming models. The first is Imperative — plain Java, no dependency injection, no annotations, direct control over the server lifecycle. This is what Helidon SE always was. For existing SE applications, upgrading to 27 is effectively a rename, not a rewrite, provided you clear the breaking changes below.

The second model is Declarative: annotation-driven, with build-time DI that generates Imperative code at compile time — no runtime reflection, no startup overhead. The approach mirrors what Quarkus and Micronaut have done for years. Helidon is late to build-time, but doing it carefully: Declarative ships as a preview and won’t finalize until Helidon 29 LTS, expected in 2028. That’s two full cycles of feedback before it hardens. Use Imperative in production for now.

MicroProfile Users: Do Not Upgrade Yet

This is the sharpest edge in the release. Helidon MP — CDI, JAX-RS, MicroProfile Config, MicroProfile Health, all of it — is no longer part of the core Helidon repository. It has been extracted to a standalone helidon-microprofile project that will release independently. As of this writing, no release date exists. If your application uses @Inject, @Path, or any MicroProfile specification API, upgrading to Helidon 27 will break it. Stay on Helidon 4.5.x LTS and track progress at github.com/helidon-io/helidon/issues/12282.

Oracle is clearly betting enterprise teams will migrate toward Core APIs over time. That might be right in the long run. It doesn’t help teams with large MP codebases today. Releasing Helidon 27 without a shipped replacement for MicroProfile is a real gap, and anyone planning an upgrade should factor that in.

Breaking Changes to Check

Three changes can silently break applications if missed. The full list is in the official CHANGELOG.

HTTP Method Case Sensitivity

HTTP method names are now case-sensitive throughout the framework. Every route definition and configuration entry using lowercase method names — get, post, put, delete — must be updated to uppercase. Security configuration has a temporary backward-compat layer that logs a migration warning, but application routing does not. Check your YAML and properties files:

# Helidon 4.x — worked fine
routing:
  method: get

# Helidon 27 — must be uppercase
routing:
  method: GET

ScopedValue Replaces ThreadLocal Context

Helidon’s internal context propagation now uses JDK ScopedValue instead of ThreadLocal. This aligns with the direction Java has taken since JDK 21 — ThreadLocal breaks inheritance semantics with virtual threads. If your code reads or writes Helidon’s context object directly, audit those paths. ScopedValue bindings are immutable within their scope; code that mutated context values will need restructuring.

Dependency Bumps

OpenTelemetry moves to 1.65.0 and Micrometer to 1.17.1. If your observability stack depends on specific span or meter APIs, review the respective changelogs before upgrading.

Two New Modules Worth Knowing

Helidon 27 adds two production-ready modules that close real capability gaps.

Helidon Messaging brings blocking Kafka, JMS, and Apache Pulsar support — no reactive streams required. The annotation model is straightforward:

@Service.Singleton
final class OrderValidator {
    @Messaging.ReceiveFrom("orders")
    @Messaging.SendTo("validated-orders")
    String validate(String order) {
        // synchronous business logic
        return order;
    }
}

Broker configuration lives in YAML, keeping routing logic out of application code. For teams that abandoned reactive Helidon messaging because of its complexity, this blocking API is a direct, less painful replacement.

Helidon Data JDBC is a compile-time repository layer. You write the SQL and the interface; Helidon generates the JDBC plumbing at build time. It supports Jakarta Persistence with both EclipseLink and Hibernate ORM. The result is readable repositories with no reflection overhead at runtime — a meaningful advantage over proxy-based JPA implementations in latency-sensitive services.

Your Upgrade Path

The decision comes down to which programming model you’re on:

• On Helidon SE? You can upgrade to Helidon 27 Core Imperative. Update HTTP method casing in all configuration, audit any direct context access, and review OTel/Micrometer usage. The InfoQ breakdown covers the full migration checklist.
• On Helidon MP? Stay on 4.5.x LTS. The standalone MicroProfile module is coming but isn’t here. Upgrading now means replacing your entire programming model without the tooling to do it cleanly.

Helidon 27 is architecturally coherent — a framework that finally aligns with the JDK cadence, a Declarative API built at compile-time the right way, and new modules that address real capability gaps. The MicroProfile extraction is the right long-term direction executed without the safety net enterprise teams need. Watch the issue tracker and hold off on MP codebases until that standalone release ships.