Skip to content
javahacks.dev
Play Framework

Fix Play Framework Compile Errors After Upgrading sbt

Fix the compile and resolution errors that follow a Play Framework or sbt upgrade, from the moved plugin group ID to the Akka to Pekko package change.

5 min read
Summarize in AI
Flat illustration of a log with a failing line and a wrench, with the Docker, Gradle and Apache Maven logos.

The upgrade changed one number in plugins.sbt and the build produces a wall of red. Almost all of it comes from three causes, and they look different depending on the stage. This post reads each message and says what to change. The context for build tooling is in Maven and Gradle errors, and Play's own structure in Play Framework architecture.

Stage 1: the plugin does not resolve

Text
[error] sbt.librarymanagement.ResolveException: Error downloading com.typesafe.play:sbt-plugin;2.9.x
[error] not found: https://repo.scala-sbt.org/...

Play 3.0 moved to a new organization. The plugin is published as org.playframework:

project/plugins.sbtscala
addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.8")

while Play 2.9 and earlier use "com.typesafe.play" % "sbt-plugin". A new version number with the old group fails to resolve. Look up the current release in the Play release notes rather than copying a version from an old project.

The same move applies to the Play ecosystem plugins you declare directly, such as the Ebean plugin, which publish separate versions for Play 3.

Stage 2: sbt and Scala versions

Play pins what it supports. In project/build.properties:

Text
sbt.version=1.10.7

Use an sbt version the plugin supports; the error when it does not is usually an UnsupportedClassVersionError or a binary incompatibility message from the plugin. The scalaVersion in build.sbt must be a supported Scala 2.13 or 3 release for your Play version, and Play 3.0 requires a recent JDK. If the build fails with a class file version error, see UnsupportedClassVersionError.

Stage 3: imports from Akka

Play 3.0 replaced Akka with Apache Pekko after Akka changed its licence. The compile errors read:

Text
[error] /app/controllers/JobController.java:4:21: package akka.actor does not exist
[error] import akka.actor.ActorSystem;

Change the packages:

java
// Play 2.9
import akka.actor.ActorSystem;
// Play 3.0
import org.apache.pekko.actor.ActorSystem;

The same applies to akka.stream, akka.pattern and other packages. The classes keep their names, so a global replace of akka. with org.apache.pekko. handles most code. Configuration keys move too: akka { ... } blocks in application.conf become pekko { ... }, and play.akka.* keys become play.pekko.* in some cases. If a third-party library depends on Akka, you may need a version built for Pekko or run Play 2.9.

Stage 4: other breaking changes

MessageCause
cannot find symbol for Http.Request methodsRequest handling API changed; pass the request explicitly (Http.Request request)
not found: value ... in Scala routesController or route signatures changed
Warnings about javaxInjectDependency injection annotations; check the migration guide for your version

Read the migration guide for your exact upgrade, because each release changes small APIs. Upgrading one step at a time (2.8 to 2.9 first, then 3.0) isolates the failures.

A clean order to upgrade

  1. Update project/build.properties to a supported sbt.
  2. Change the plugin group and version in project/plugins.sbt.
  3. Run sbt clean update until dependency resolution succeeds.
  4. Replace akka imports and configuration if you move to 3.0.
  5. Run sbt compile and fix API changes, then sbt test.

Pin the sbt version in one file

The sbt launcher reads the version from project/build.properties, and the plugin version from project/plugins.sbt. The two have to be compatible, and a mismatch is the most common cause of a build that fails before compiling anything:

Text
sbt.version=1.10.7

A new Play release raises the minimum sbt version, and the migration notes name it. Change build.properties first, run sbt about to confirm the launcher took it, and only then change the plugin. Doing both at once leaves two possible causes for one error.

See what sbt resolved

When a dependency error appears, the build already knows the answer. Two commands print it:

Shell
sbt evicted
sbt dependencyTree

evicted lists the libraries where sbt chose a newer version than one a dependency asked for. A warning about binary incompatibility there is a real defect: a library compiled against Jackson 2.14 running with 2.17 can work, and a library compiled against Akka 2.6 running with a different major cannot. dependencyTree shows who brought each version in, which tells you which direct dependency to upgrade.

Clear stale output before blaming the code

Play generates sources for routes and templates under target, and an upgrade can leave generated classes that no longer match the framework. Errors that mention a generated file, such as target/scala-2.13/routes/main/router/Routes.scala, point here. Remove the generated output and the sbt metadata caches, then rebuild:

Shell
sbt clean
rm -rf target project/target project/project
sbt compile

If a resolution error persists, the coursier cache may hold a broken download. Delete the artifact directory named in the error under ~/.cache/coursier and retry.

Play 2.9 and Play 3 use different actor libraries

Play 2.9 stays on Akka, and Play 3.0 moved to Apache Pekko, so the imports differ: akka.actor on one side, org.apache.pekko.actor on the other. A project that upgrades from 2.9 to 3.0 must change the imports in its own code and replace Akka-based libraries with Pekko versions. Mixing the two on one classpath compiles and then fails at startup when two actor systems try to configure themselves. The same applies to akka-http and its Pekko equivalent.

Java and Scala versions

A Play release names the Java versions it supports, and the build's javacOptions and the CI image have to agree. A build that compiles locally and fails in CI with class file has wrong version has a JDK mismatch. For Scala, check scalaVersion in build.sbt. Play 3 cross-builds for Scala 2.13 and 3, and a dependency published only for 2.13 cannot be used from Scala 3 without the CrossVersion.for3Use2_13 setting.

scala
libraryDependencies += ("com.example" %% "legacy-lib" % "1.4.0").cross(CrossVersion.for3Use2_13)

Use that bridge only for a library with no Scala 3 release, since it is a source of subtle errors when the library uses macros.

Reading the error by stage

MessageStageFirst action
Unresolved dependencies pathPlugin resolutionCheck the plugin version and the repository settings
sbt.version ... is not supportedLauncherUpdate build.properties
object akka is not a member of packageCompileReplace imports for Pekko, or add the Akka dependency
not found: type ActionCompileController base classes and injection changed, see the migration notes
Routes.scala errorsGenerated sourcesClean and check the routes file syntax

Where this does not apply

If the build compiles and the application fails at start-up, read the log: configuration keys and dependency injection errors differ from compile errors. The Play migration guides list every change for each release, and the sbt documentation covers the build side.

Also inDevOps
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.