Could Not Find or Load Main Class Error | Java

Key Takeaways

• The error usually means the launcher cannot resolve the requested main class from its binary name and runtime search path.
• For compiled classes, use the exact, case-sensitive class name without a filename extension. Include the package name when the class declares one.
• Point the class path at the output directory above the package hierarchy, and put launcher options before the main-class name.
• Inspect the complete error, compiled output, and actual launch configuration before changing dependencies or investigating custom class loaders.

The Java could not find or load main class error usually means the launcher cannot locate the entry-point class using the name and search path you supplied. Start with the launch command, package declaration, and compiled output—not JVM internals. The launcher must load the requested class before it can invoke its main method.

Error: Could not find or load main class MyClass
Caused by: java.lang.ClassNotFoundException: MyClass

Keep both lines: the cause identifies the class that lookup could not find. If a different exception or class name appears, follow that evidence rather than treating every startup failure as the same classpath problem.

Start With a Minimal Compile-and-Run Example

Save this as MyClass.java in an empty directory:

public class MyClass {
    public static void main(String[] args) {
        System.out.println("My class is working!");
    }
}

With a JDK installed and its tools available in your terminal, run these commands from that directory:

java -version
javac -version
javac MyClass.java
java -cp . MyClass

javac MyClass.java creates MyClass.class beside the source file. The final command searches the current directory, represented by ., and launches the compiled class. Expected output:

My class is working!

Here, MyClass is the binary class name—the name the runtime uses to identify the class—not a filename. Without an explicit class path or a CLASSPATH environment setting, java MyClass also searches the current directory.

If these commands are unfamiliar, start with our Java beginner tutorial. For installation choices, see which Java version you should use.

Check the Class Name and Capitalization

For the example above, this requests a different class and fails:

java myclass

Use MyClass, not myclass. Class lookup uses the exact binary name; correcting the filesystem path does not correct a misspelled class name.

Distinguish Class Names From Source Filenames

java MyClass.class is not the compiled-class launch form. However, java MyClass.java is valid source-file mode on Java 11 and later: the launcher compiles source into memory and executes it. These are different workflows, not interchangeable filename spellings.

As an alternative to compiling the earlier example, put only MyClass.java in a fresh directory and run:

java MyClass.java

The Java 11 launcher documentation documents this source-file workflow. For the remaining troubleshooting steps, assume you are launching compiled classes.

Run a Packaged Java Class From the Class-Path Root

A package adds two requirements: use the package-qualified class name, and preserve its directory hierarchy in the compiled output. Save this example as src/com/myproject/MyClass.java:

package com.myproject;

public class MyClass {
    public static void main(String[] args) {
        System.out.println("My class is working!");
    }
}

From the project root, compile and launch it:

javac -d out src/com/myproject/MyClass.java
java -cp out com.myproject.MyClass

The compiler's -d out option writes classes beneath out, creating the package directories as needed. The resulting layout is:

project/
|-- src/com/myproject/MyClass.java
`-- out/                         <-- class-path root
    `-- com/
        `-- myproject/
            `-- MyClass.class

The runtime needs out, not out/com/myproject, as the class-path entry. Conceptually, it combines that root with com/myproject/MyClass.class. The javac documentation explains the package-based output layout.

Running java com.myproject.MyClass without -cp out works only if the effective class path already includes the root containing com/. Changing into the deepest package directory and running java MyClass does not remove the package encoded in the compiled class.

Fix Classpath Syntax and Launcher Option Ordering

Put Launcher Options Before the Main Class

The launch structure is java [options] mainclass [application arguments]. Anything after the main-class name is passed to the application, so the original ordering below does not set the launcher's class path:

# Incorrect: -cp is after the main-class name
java MyClass -cp /usr/local/path

# Correct, assuming this directory contains MyClass.class
java -cp /usr/local/path MyClass

For the packaged example, this sets the class path and passes two application arguments:

java -cp out com.myproject.MyClass first second

The arguments are available through args; this example does not print them. The launcher also accepts --class-path as an alternative to -cp.

Use the Right Separator and Quote the Class Path

Classpath entries are separated by : on Linux and macOS and ; on Windows. Quote the complete value, particularly when paths contain spaces. For example, if dependencies are stored in a project-local lib directory:

Linux or macOS:

java -cp "out:lib/*" com.myproject.MyClass

Windows:

java -cp "out;lib/*" com.myproject.MyClass

The lib/* classpath entry includes JAR files in that directory; it does not recursively include every nested directory. Explicit -cp overrides CLASSPATH, rather than appending to it. Prefer a project-specific command or build configuration over changing a global environment variable.

Inspect the Resolved Class Path and Working Directory

For a HotSpot-based JDK, inspect the settings for the classpath value you intend to use:

java -XshowSettings:properties -cp out -version

Look for java.class.path and user.dir. This prints settings and version information without running your application. A relative entry such as out must resolve from the directory where you launch the process, not necessarily the directory shown in your editor.

Read the Cause: Similar Errors Need Different Fixes

Compare the full diagnostic, not just its first line:

ClassNotFoundException reports failed name-based loading. NoClassDefFoundError is a linkage error encountered when a required class definition cannot be loaded. A missing dependency can therefore prevent the launcher from loading the main class even when its own class file exists.

The traditional public static void main(String[] args) signature used here remains a portable choice. Newer Java releases also accept additional main-method forms, so do not assume that every valid entry point must look exactly like this example.

Inspect IntelliJ, Maven, and Gradle Launches

IntelliJ IDEA: Check the Main Class, Module, and Output

1. Open Run → Edit Configurations and select the failing Application configuration.
2. Set Main class to the fully qualified name, such as com.myproject.MyClass.
3. Check the selected runtime, Working directory, and Use classpath of module. Remove unintended classpath overrides from VM options.
4. For IntelliJ's own compiler, inspect File → Project Structure → Modules → Paths and locate the compiled class under the configured output directory.
5. Inspect the launch command in the Run console. If it uses an argument file or temporary classpath JAR, inspect that indirection rather than assuming the visible command contains every dependency.

The Application configuration reference explains module selection and command-line shortening; module structure settings covers compiler output. If builds are delegated to Maven or Gradle, inspect that tool's output instead.

Maven: Compile the Application Module and Inspect Plugin Settings

In an existing Maven project, the conventional source location for this example is src/main/java/com/myproject/MyClass.java, and the standard compiled output is target/classes/com/myproject/MyClass.class. Run from the application module's directory, not an unrelated parent or sibling module. The Maven POM reference documents these directory settings.

If your project uses the Exec Maven Plugin, compile before invoking its Java goal:

mvn -X compile exec:java -Dexec.mainClass=com.myproject.MyClass

-X enables Maven debug output. Check the resolved mainClass, output directory, and classpath additions. The exec:java goal runs inside Maven's existing JVM with a plugin-managed class loader, so there is no separate application java command to copy. Use the goal's classpath configuration, not Maven's own process class path, to diagnose this launch.

Gradle: Verify mainClass and the Runtime Classpath

For an existing Gradle project, this complete build.gradle.kts configures the Application plugin for the packaged example:

plugins {
    application
}

application {
    mainClass = "com.myproject.MyClass"
}

Place the source in src/main/java/com/myproject/MyClass.java. With the project's wrapper available, run on Linux or macOS:

./gradlew run --info

On Windows Command Prompt, use gradlew.bat run --info. The Application plugin's run task compiles the main source set and launches a JVM with its runtime dependencies. With info logging, inspect the process working directory and command.

The Java plugin normally writes main Java classes to build/classes/java/main. Also check the main source set's runtimeClasspath; a dependency available during compilation is not proof that your custom launch task includes it. See the Java plugin's source-set and dependency configuration.

Check Whether You Are Launching a Module or a JAR

Classpath advice applies to classpath launches. A named-module application instead uses --module-path and --module, with a module name separate from the class name. For an already-built module named com.myproject.app under mods, the launch form is:

java --module-path mods --module com.myproject.app/com.myproject.MyClass

Check the module name, resolved module location, and main class together. For an executable JAR launched with java -jar, check its Main-Class manifest entry and packaging; ordinary -cp settings are ignored in that launch mode. The launcher reference distinguishes these modes.

How Java Class Loading Relates to This Error

Loading Is Not JIT Compilation

Loading brings a class definition into the JVM. Execution can involve interpretation and just-in-time compilation, but that is separate from finding the class definition. Classes may be loaded as execution needs them; implementations can also load or resolve classes earlier within the specification's rules. See our explanation of the Java JIT compiler for the execution side.

Modern Loaders and Delegation

• Bootstrap loader: loads core platform classes.
• Platform loader: loads additional platform classes.
• Application/system loader: normally loads application classes from the class path and application modules.

Parent delegation means a loader usually asks its parent before searching its own sources. This is a model, not a universal search trace: built-in module-aware loaders and custom loaders have additional behavior. The bootstrap loader is not a final fallback that searches arbitrary application directories.

The old extension mechanism was removed in Java 9; copying libraries into jre/lib/ext is not a current fix. Oracle's migration guide explains the removal and platform-loader transition.

Custom Loaders Are Not the First Fix

Custom class loaders can obtain class definitions from application-specific sources. Class identity includes both the binary name and its defining loader, so identically named classes defined by different loaders are distinct runtime types. Loader boundaries can therefore explain visibility problems—but investigate them only after verifying the ordinary launch configuration.

Your shortest diagnostic sequence is: capture the command and cause, verify compilation, match the package-qualified name to the output layout, then check runtime dependencies and tool configuration. Change one variable at a time.

FAQ

Why does Java say it could not find or load the main class?

The launcher could not resolve or load the requested entry-point class. Check its exact name, package declaration, compiled output, and runtime search path, then read the cause for a missing dependency or name mismatch.

How do I set the class path when running a Java class?

Put the classpath option before the class name, such as java -cp out com.myproject.MyClass. Separate multiple entries with a colon on Linux or macOS and a semicolon on Windows; explicit -cp overrides CLASSPATH.

How do I run a Java class that declares a package?

Compile with javac -d out src/com/myproject/MyClass.java, then run java -cp out com.myproject.MyClass from the project root. The class-path entry is out, the directory above the package hierarchy.

Does java MyClass.java work, or must I compile first?

Java 11 and later support source-file mode, so java MyClass.java can compile and run source directly. For an already-compiled class, use java MyClass without a filename extension and supply the appropriate class path.

Why does this error occur in IntelliJ, Maven, or Gradle?

The configured main class or runtime classpath may not match the build output. Inspect IntelliJ's selected module and launch command, Maven Exec's resolved settings with -X, or Gradle's run command with --info, and confirm that the compiled class exists.

Further Reading

• Java launcher reference — classpath, source-file, JAR, and module launch modes.
• Java compiler reference — compilation options and package-based output directories.
• Java Language Specification: Execution — startup, loading, and accepted main methods.
• ClassLoader API — built-in loaders and delegation behavior.
• JVM Specification: Loading, Linking, and Initializing — class identity and loading failures.
• IntelliJ Application run configurations — entry point, module classpath, and command shortening.
• Exec Maven Plugin Java goal — main-class and runtime classpath configuration.
• Gradle Application plugin — mainClass, the run task, and modular applications.