"Could not find or load main class" in Java: what should a beginner do?

"Could not find or load main class": a familiar fear for every Java beginner

You've just started learning Java, wrote your first HelloWorld.java, held your breath, and pressed Enter in the terminal… And instead of the coveted greeting, you saw a cold message:

Error: Could not find or load main class HelloWorld\nCaused by: java.lang.ClassNotFoundException: HelloWorld

Sound familiar? If so, you are not alone. This question on Stack Overflow has gathered millions of views and is the absolute record holder among errors for beginner Java developers. The good news: the cause is almost always trivial, and the solution takes 30 seconds. The bad news: if you don't understand why it happened, the error will haunt you again and again.

In this article, we will break down all possible causes of "Could not find or load main class" with specific examples. You will learn not just to fix the error, but to understand how Java looks for your class. Let's go!

The short version: what is the JVM trying to say?

When you write java ClassName, the Java Virtual Machine (JVM) receives a command: "Find a class with that name and run its main method." If the JVM cannot find the .class file with the required name or cannot find the correct main method in it, it panics and throws this error.

It's important to understand: Java works with bytecode (.class files), not with source code (.java). You first compile .java into .class using the javac command, and then run the .class using the java command. If something goes wrong at the second step, you get the dreaded error.

Scenario 1: You forgot to compile the file

The most common reason, especially for those who just opened the terminal. You write:

java HelloWorld

But you didn't run this beforehand:

javac HelloWorld.java

Without compilation, the HelloWorld.class file simply doesn't exist. The JVM honestly tries to find it, but can't and throws the error.

How to check?

\n
• Look in the current folder: is there a HelloWorld.class file?
\n
• If only HelloWorld.java is there — compile it.
\n
• If neither is there — check if you are in the right directory.
\n

Scenario 2: Typo in the class name (case matters!)

Java is a strongly typed language and is case-sensitive. If your class is named HelloWorld, but you write:

java helloworld\njava HelloWorld.class\njava HelloWorld.java

— the JVM won't understand you. The class name must match the file name exactly, character by character. Yes, HelloWorld and helloworld are different names for the JVM.

Scenario 3: Problems with package (the sneakiest trap)

As soon as you start using packages, the rules change. Let's say you have a file:

// File: src/com/pythonlib/MyApp.java\npackage com.pythonlib;\n\npublic class MyApp {\n    public static void main(String[] args) {\n        System.out.println("Hello from PythonLib!");\n    }\n}

Many beginners do this:

cd src\njavac com/pythonlib/MyApp.java   // compilation succeeds\njava MyApp                        // ERROR!

Why? Because the fully qualified class name is now com.pythonlib.MyApp, not just MyApp. The JVM looks for the class by its full na