The java.lang.NoClassDefFoundError when running sbt on Windows after installing the sbt-java MSI is typically caused by an incorrect Java Home path or a corrupted classpath environment variable. The most effective fix is to verify that the JAVA_HOME environment variable points to the correct JDK installation directory and to ensure that sbt can locate it via the PATH. Reinstalling the MSI often resets these variables correctly, but manual verification is usually required.
Understanding the Error Context
The error java.lang.NoClassDefFoundError indicates that the Java Virtual Machine (JVM) attempted to load a class definition at runtime but could not find the compiled bytecode for that class in the classpath. In the context of sbt (Simple Build Tool), this almost always happens because the underlying Java process cannot initialize properly due to missing dependencies or misconfigured environment variables. When you install the sbt-java MSI package, it is designed to configure your system to run Java-based build tools without requiring a separate manual JDK installation in many cases, or it sets up specific paths for the bundled JRE.
If the environment variables are not set correctly after installation, sbt may attempt to launch with a partial or empty classpath, leading to immediate failure before any build logic is executed. This is distinct from a missing source file error; it is a fundamental infrastructure issue where the tool cannot even start its internal JVM. Users often encounter this immediately after trying to run sbt compile or simply sbt for the first time post-installation.
Verifying Environment Variables
The primary suspect for this issue on Windows is the JAVA_HOME environment variable. The sbt launcher script relies on this variable to determine which Java executable to use. If JAVA_HOME is unset, points to a non-existent directory, or points to a JRE instead of a full JDK (depending on your sbt version requirements), the classloader will fail. To check this, open the Command Prompt and type echo %JAVA_HOME%. If this returns nothing or an incorrect path, you must update it.
To update JAVA_HOME, navigate to System Properties > Advanced > Environment Variables. Look for JAVA_HOME in the System variables section. Ensure the value points to the root directory of your JDK installation, such as C:\Program Files\Java\jdk-17. Do not include the bin subdirectory in this path. After changing it, you must restart your Command Prompt or IDE to pick up the new values. It is also critical to check the PATH variable. Ensure that %JAVA_HOME%\bin is present in the PATH so that the java command is accessible globally. If you have multiple Java versions installed, the order in the PATH matters; the desired JDK should appear earlier in the list than any other Java installations.
Reinstalling the sbt-java MSI
If the environment variables appear correct but the error persists, the MSI installation itself may have failed to register the necessary registry keys or shell associations. A clean reinstall is often more reliable than troubleshooting individual settings. Before reinstalling, it is advisable to uninstall the existing sbt-java package via the Control Panel or Settings > Apps. This ensures that old configuration remnants do not interfere with the new installation.
During reinstallation, pay close attention to the setup wizard. Some versions of the sbt-java installer offer options to automatically configure environment variables. If available, select the option to "Add sbt to PATH" or "Configure JAVA_HOME". If you are using a custom JDK installation alongside sbt, choose the option that allows you to specify the JDK location manually. After the installation completes, open a fresh Command Prompt window and run sbt --version. This command forces sbt to initialize its environment and report its status. If it outputs the version number without errors, the classpath issues have been resolved.
Checking for Conflicting Java Installations
Windows systems often accumulate multiple Java installations over time, which can lead to conflicts. For instance, having both Oracle JDK and OpenJDK installed, or having older JREs lingering in the System32 folder, can cause the wrong java.exe to be invoked. Use the command where java in the Command Prompt to see all locations where the java executable is found. The first path listed is the one that takes precedence. If the first path does not correspond to your intended JAVA_HOME, you need to adjust your PATH variable to prioritize the correct directory.
In some cases, users may need to explicitly tell sbt which Java home to use if the automatic detection fails. While the previous draft suggested editing scripts, a safer approach is to set the SBT_OPTS environment variable. You can add -Djava.home="C:\Path\To\Your\JDK" to SBT_OPTS. This overrides the default behavior without modifying the core installation files. This method is particularly useful if you are working with a project that requires a specific Java version different from the system default.
Clearing Cached State
Occasionally, sbt caches metadata about the Java environment in its local repository. If you changed your JAVA_HOME or updated your JDK, sbt might still be trying to use cached classes from the previous configuration. Clearing the cache can force sbt to re-evaluate the classpath. Delete the .ivy2 and .sbt directories in your user home folder (%USERPROFILE%\.ivy2 and %USERPROFILE%\.sbt). Be aware that this will remove locally downloaded dependencies, so you may need to wait for sbt to re-download them during the next build. This step is often the final solution when environment variables are verified to be correct.
Frequently Asked Questions
Why does sbt work in IntelliJ but fail in CMD?
This usually happens because your IDE has its own embedded JDK configuration that overrides system environment variables. IntelliJ IDEA often uses its bundled JDK or a user-specified SDK that is independent of the Windows JAVA_HOME. To fix this, ensure that the Project Structure SDK in IntelliJ matches the JDK configured in your system environment variables.
Can I use sbt without installing the JDK separately?
Yes, the sbt-java MSI includes a JRE sufficient for running sbt itself. However, if your Scala project requires a specific JDK version for compilation, you must still install that JDK and point JAVA_HOME to it. The bundled JRE is primarily for the sbt launcher, not for compiling your application code.
What if my JAVA_HOME contains spaces?
Spaces in the JAVA_HOME path can sometimes cause parsing errors in batch scripts. Enclose the path in quotes within the Environment Variables dialog. For example, use "C:\Program Files\Java\jdk-17". Most modern sbt versions handle quoted paths correctly, but ensuring proper quoting prevents legacy script issues.
How do I know if sbt is using the correct Java version?
You can check by running sbt "show javaHome" in the sbt console. This command prints the exact directory path that sbt has detected for the Java Home. Compare this output with your expected JAVA_HOME value. If they differ, your environment variables or SBT_OPTS are misconfigured.
Is it safe to delete the .sbt folder?
It is generally safe to delete the .sbt folder in your user home directory, as it contains only cached metadata and downloaded dependencies. Your actual project source code remains untouched. Deleting it forces sbt to rebuild its cache, which can resolve persistent classloading errors related to stale artifacts.