You've probably been there: you run sbt compile in your terminal, it finishes successfully, and you're ready to ship. But when you look back at your IDE, the screen is a sea of red. Your imports are screaming that classes don't exist, and the "Import Build" button in Metals seems to be spinning in a void. It's maddening because the code is correct, but the IDE doesn't believe you.

// In your IDE, this looks like an error:
import com.company.internal.NewFeatureClient

def process(): Unit = {
  // Error: Not found: type NewFeatureClient
  val client = new NewFeatureClient() 
  client.execute()
}

The Disconnect Between sbt and your Editor

The problem isn't your code, and it isn't even really Metals. The issue is that sbt is a heavy-duty build tool designed for the CLI, but IDEs need a way to ask "what is the classpath for this specific file?" thousands of times a minute as you type. In the old days, the IDE tried to mimic the build tool, which led to those legendary "refreshing project" hangs that lasted ten minutes.

This is where Bloop comes in. Bloop is a build server. Instead of the IDE trying to be a build tool, sbt (or Mill) generates a configuration file that tells Bloop: "Here is exactly where every jar and source file lives." Bloop then stays resident in memory, providing a lightning-fast API that Metals queries to resolve symbols.

The "ghost errors" you're seeing happen when the Bloop configuration is stale. You added a dependency to build.sbt, the terminal knows about it, but the Bloop server is still holding onto the old classpath. You're essentially talking to a version of your project that exists in the past.

Synchronizing the Build Server

To fix this, you don't just "restart the IDE"—that's the nuclear option and it rarely solves the underlying config mismatch. You need to force the build tool to re-emit the Bloop configuration.

• If you're using Metals, you'll see a notification to "Import Build." When you click this, Metals calls sbt, which then updates the .bloop/ directory in your project root.
• If that's hanging, the most reliable fix is to clean the Bloop state entirely. I usually do this by deleting the .bloop/ folder and the .metals/ folder and then triggering a fresh import.

Once the .bloop/ directory is updated, Bloop loads the new classpath into memory. Suddenly, the red squigglies disappear because Metals can now ask Bloop, "Where is NewFeatureClient?" and Bloop can answer instantly with the exact path to the jar, without having to boot up a full sbt session.

I've found that as your project grows into a multi-module build, this becomes critical. Bloop allows for incremental compilation that is far more granular than what you get from a standard sbt run, because it tracks the dependency graph at a much tighter level. It essentially turns your compilation process from a "batch" job into a "service."

📋 Practical Task

Resolving a Stale Classpath in a Multi-Module Project

You are working on a project with two modules: core and api. The api module depends on core. You have just added a new case class UserSession to the core module.

The Situation:
1. You run sbt compile and it succeeds.
2. In the api module, you try to use UserSession, but the IDE marks it as an unresolved symbol.
3. You have already tried clicking "Import Build" once, but the error persists.

Your Goal: Perform a deep reset of the build server to force a clean synchronization between sbt and Bloop. Describe the specific steps you would take regarding the project's hidden directories and the Metals action required to ensure the api module can finally "see" the UserSession class from the core module.