Skip to content
javahacks.dev
Play Framework

Play 2.8 to 3 Migration Steps for Your Existing Project

Migrate a Play 2.8 application to Play 3: go through 2.9 first, update sbt and Java, swap Akka for Pekko, fix removed APIs and verify before deploying.

5 min read
Summarize in AI
Flat illustration of a controller, a service and a repository stacked above a database, with the OpenJDK, PostgreSQL and Apache Maven logos.

An application on Play 2.8 is not one step from Play 3. Play 2.8 is on Akka 2.6, Scala 2.12 or 2.13 and Java 8 or later. Play 3.0 is on Pekko, Scala 2.13 or 3 and Java 11 or later. The responsible route is two migrations rather than one: 2.8 to 2.9, which is still Akka and carries the toolchain and API changes, then 2.9 to 3.0, which is the Pekko rename. Doing them separately means a failing test belongs to one cause. This post lays out the sequence, the build changes at each stage, the code areas that usually need edits and the checks to run, based on the migration guides published by the Play project. I link no version numbers beyond the ones I name, so check the guide for your exact patch release before you start.

Plan the order

Before changing anything, get the application to a known good state: the test suite passes, the application starts, and you have a baseline of behavior that you can compare with later. Commit that. Then do the work in three branches or three commits so you can bisect:

  1. Update to the last Play 2.8 patch release and fix its deprecation warnings.
  2. Move to Play 2.9 (toolchain, Scala and library upgrades).
  3. Move to Play 3.0 (the Pekko rename and the new coordinates).

The first step is cheap and valuable. Deprecations in 2.8 are the removals of 2.9, and the compiler tells you where. Compile with warnings visible (scalacOptions += "-deprecation") and fix what it reports before you change the version.

Step one: toolchain for Play 2.9

Play 2.9 needs a newer toolchain. sbt must be 1.9.x or later (project/build.properties), Java 11 is the minimum, and Scala 2.12 is no longer supported, so a 2.12 application must move to 2.13 or 3.3 at this point. That is its own migration if your code base is large; the Scala 2.13 collections changed (the deprecated JavaConverters, the Stream to LazyList shift) and the compiler's migration flag -Xsource:3 helps with Scala 3. Treat it as the main cost of this step.

scala
// project/build.properties
sbt.version=1.9.9

// project/plugins.sbt
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.9.4")

// build.sbt
scalaVersion := "2.13.14"

After the version bump, sbt will report incompatible dependencies. The ones to check first: scalatestplus-play (the Play test integration, which has a version tied to Play), play-json if you pinned it, slick and play-slick, and any library that depends on Akka or Akka HTTP versions. Align them with the versions the Play 2.9 migration guide lists. A library that is compiled for Scala 2.12 only, a frequent find in older code bases, needs a replacement.

Step two: API changes to watch

The guide for each version lists the removals. Areas that most often need edits in applications of this age are the following. Filters configuration: the default security headers and allowed hosts filters changed defaults over time, so check application.conf for play.filters settings and the allowed hosts requirement, which rejects requests with an unknown Host header in production. The CSRF and CORS filter options have seen clarifications as well. Evolutions and database configuration moved to HikariCP defaults; verify your pool settings. Methods on play.api.mvc.Request and helpers that were deprecated in 2.8 (older Action composition helpers, uses of play.api.libs.concurrent.Execution.Implicits) are gone; use the injected ExecutionContext. Java applications should check the play.mvc.Http API changes, such as header handling.

Compile, then fix the errors in order. Do not attempt the Pekko rename yet. Run the whole test suite, start the application in dev mode and in production mode (sbt stage, then run the script), and click through the main pages; some configuration problems appear only in production mode, where the secret key, the allowed hosts and the HTTP settings are enforced.

Step three: Play 3.0 and Pekko

Now change the coordinates and rename Akka to Pekko. The plugin group moves to org.playframework, and Twirl and other related projects moved with it:

scala
// project/plugins.sbt
addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.5")

Then rename imports from akka. to org.apache.pekko. across app/, test/ and conf/. In configuration, the actor system keys move from akka. to pekko., and Play's own settings that exposed Akka configuration have Pekko counterparts under play.pekko; look in the framework's reference.conf for the exact keys and compare with what your application.conf overrides. Libraries move in the same way: akka-http becomes pekko-http, and so on. The dedicated post on the Pekko move covers the rename and the library risk in more detail.

Shell
grep -rn "akka" app test conf build.sbt project/*.sbt | grep -v "^Binary"

That grep should come back empty at the end, apart from comments and documentation. A leftover reference usually indicates a configuration key that silently does nothing: Play starts, the setting you tuned (a dispatcher size, a timeout) is not applied and the symptom appears under load months later.

Checks that catch the quiet breakages

Compile errors are the easy part. The dangerous failures are behavioral. Check JSON serialization: play-json has its own versioning, and format defaults for options and enumerations have had subtle changes, so compare responses of a few key endpoints byte for byte before and after. Check dependency injection startup, since a Guice binding that depended on an Akka-typed class needs the Pekko type. Check scheduled tasks and actors for the rename in actor paths. Load the application with the same test you ran before and compare latency and memory; a changed thread pool configuration shows up there.

If you use sbt-native-packager and Docker publishing, rebuild the image and run it, since the packaging plugin versions move with Play. Look at the startup logs for warnings about deprecated settings: Play logs configuration it no longer recognizes, and those lines are worth reading once.

Where this does not apply

If you are on 2.7 or older, add another stage: 2.8 first, by the same method. If your application is Java only, the Scala 2.12 to 2.13 work is smaller, but the sbt, Java 11 and Pekko steps remain. And if a critical library has no release for Play 3 or Pekko, stop at 2.9, which is a supported and complete state, until the library catches up. A half-migrated application that runs on neither is the one outcome to avoid.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.