cannot find symbol

The “cannot find symbol” error means the Scala compiler cannot locate a class, method, or field anywhere on the classpath during compilation.

What It Means

Scala compilation proceeds in phases: parsing, naming, typing, and code generation. The “cannot find symbol” error occurs in the naming/typing phase when the compiler encounters a name it has never seen in any loaded source file, compiled class, or library JAR. Unlike “not found: value” (which applies to the current scope), this error means the entire classpath was searched and the symbol does not exist anywhere.

Why It Happens

• A library dependency is missing from build.sbt or build.sc.
• The library version specified does not include the symbol (removed or renamed).
• The symbol is defined in another module of a multi-module project but that module is not listed as a dependency.
• The build cache is stale — incremental compilation missed a recompiled dependency.
• A Scala 2 library is used in a Scala 3 project without a cross-version bridge.
• The symbol was generated by a macro or code generator that hasn’t run yet.

How to Fix It

1. Add the missing dependency to build.sbt

// build.sbt
// ❌ cannot find symbol: circe (import io.circe._ fails)
// ✅ Add the library
libraryDependencies += "io.circe" %% "circe-core" % "0.14.7"

// Run: sbt update

2. Check the library version for symbol availability

// If the symbol was added in version 2.0 but you're using 1.0:
libraryDependencies += "com.typesafe" % "config" % "1.4.3" // latest

Check the library’s release notes or API diff to find when the symbol was introduced or removed.

3. Add inter-project dependencies in multi-module builds

// build.sbt for a multi-module project
lazy val core = project.in(file("core"))
lazy val api = project.in(file("api")).dependsOn(core) // api needs core

// Without dependsOn(core), the api module cannot find symbols from core

4. Clean and rebuild

# Remove all cached compilation artifacts
sbt clean

# Recompile from scratch
sbt compile

5. Check Scala version compatibility

// Some libraries support Scala 2.13 but not Scala 3.x
// ❌ Using a Scala 2.13-only library in a Scala 3 project
scalaVersion := "3.5.0"
libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "2.4.0"

// Use the Scala 3 compatible version or check for a -cross artifact
// libraryDependencies += ("org.scala-lang.modules" %% "scala-parser-combinators" % "2.4.0").cross(CrossVersion.for3Use2_13)

6. Verify macro and code generation runs

If the symbol is generated by a macro annotation or code generator:

# Run code generation explicitly
sbt "compile"
# or for specific generators, check the plugin's documentation