«Could not find or load main class» en Java: ¿qué hacer si eres principiante?

«Could not find or load main class»: el miedo familiar de todo principiante en Java

Acabas de empezar a estudiar Java, escribiste tu primer HelloWorld.java, con el corazón en un puño presionaste Enter en la terminal… Y en lugar del esperado saludo, viste un frío mensaje:

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

¿Te suena familiar? Si es así, no estás solo. Esta pregunta en Stack Overflow ha acumulado millones de visitas y es el récord absoluto entre los errores de los desarrolladores principiantes de Java. La buena noticia: la causa casi siempre es trivial y la solución toma 30 segundos. La mala noticia: si no entiendes por qué ocurrió, el error te perseguirá una y otra vez.

En este artículo analizaremos todas las causas posibles de la aparición de «Could not find or load main class» con ejemplos concretos. Aprenderás no solo a corregir el error, sino a entender cómo Java busca tu clase. ¡Allá vamos!

Brevemente sobre lo principal: ¿qué intenta decir la JVM?

Cuando escribes java NombreDeLaClase, la máquina virtual de Java (JVM) recibe la orden: «Encuentra la clase con ese nombre y ejecuta su método main». Si la JVM no puede encontrar el archivo .class con el nombre requerido o no encuentra en él el método main correcto, entra en pánico y muestra este error.

Es importante entender: Java trabaja con bytecode (archivos .class), no con código fuente (.java). Primero compilas el .java a .class con el comando javac, y luego ejecutas el .class con el comando java. Si algo sale mal en el segundo paso, obtienes el famoso error.

Escenario 1: Olvidaste compilar el archivo

La causa más común, especialmente entre quienes acaban de abrir la terminal. Escribes:

java HelloWorld

Pero antes no ejecutaste:

javac HelloWorld.java

Sin compilación, el archivo HelloWorld.class simplemente no existe. La JVM intenta honestamente encontrarlo, pero no lo encuentra y muestra el error.

¿Cómo verificarlo?

\n
• Mira en la carpeta actual: ¿existe el archivo HelloWorld.class?
\n
• Si solo existe HelloWorld.java — compila.
\n
• Si no existe ninguno de los dos — verifica si estás en el directorio correcto.
\n

Escenario 2: Error tipográfico en el nombre de la clase (¡las mayúsculas importan!)

Java es un lenguaje de tipado fuerte y sensible a mayúsculas y minúsculas. Si tu clase se llama HelloWorld y escribes:

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

— la JVM no te entenderá. El nombre de la clase debe coincidir con el nombre del archivo exactamente, carácter por carácter. Sí, HelloWorld y helloworld son nombres diferentes para la JVM.

Escenario 3: Problemas con package (la trampa más engañosa)

En cuanto empiezas a usar paquetes (package), las reglas del juego cambian. Supongamos que tienes el archivo:

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

Muchos principiantes hacen esto:

cd src\njavac com/pythonlib/MyApp.java   // la compilación es exitosa\njava MyApp                        // ¡ERROR!

¿Por qué? Porque ahora el nombre completo de la clase es com.pythonlib.MyApp, no solo MyApp. La JVM busca la clase por su nombre completo