Erro "Could not find or load main class" em Java: guia para iniciantes

«Could not find or load main class»: o medo familiar de todo iniciante em Java

Você acabou de começar a estudar Java, escreveu seu primeiro HelloWorld.java, e com o coração na mão apertou Enter no terminal… E em vez da saudação tão esperada, viu uma mensagem fria:

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

Familiar? Se sim, você não está sozinho. Essa pergunta no Stack Overflow já acumulou milhões de visualizações e é a recordista absoluta entre os erros de iniciantes em Java. A boa notícia: a causa quase sempre é simples, e a solução leva 30 segundos. A má notícia: se você não entender por que isso aconteceu, o erro vai te perseguir de novo e de novo.

Neste artigo, vamos analisar todas as causas possíveis do erro «Could not find or load main class» com exemplos práticos. Você vai aprender não apenas a corrigir o erro, mas a entender como o Java procura pela sua classe. Vamos lá!

Resumo: o que a JVM está tentando dizer?

Quando você digita java NomeDaClasse, a Máquina Virtual Java (JVM) recebe a ordem: «Encontre a classe com esse nome e execute o método main dela». Se a JVM não encontra o arquivo .class com o nome certo ou não encontra o método main correto dentro dele, ela entra em pânico e exibe esse erro.

É importante entender: o Java trabalha com bytecode (arquivos .class), e não com código-fonte (.java). Primeiro você compila o .java em .class com o comando javac, e depois executa o .class com o comando java. Se algo der errado na segunda etapa, você recebe o temido erro.

Cenário 1: Você esqueceu de compilar o arquivo

A causa mais comum, especialmente para quem acabou de abrir o terminal. Você digita:

java HelloWorld

Mas antes não executou:

javac HelloWorld.java

Sem a compilação, o arquivo HelloWorld.class simplesmente não existe. A JVM tenta honestamente encontrá-lo, mas não consegue e exibe o erro.

Como verificar?

\n
• Olhe na pasta atual: existe o arquivo HelloWorld.class?
\n
• Se só existe HelloWorld.java — compile.
\n
• Se não existe nenhum dos dois — verifique se você está no diretório correto.
\n

Cenário 2: Erro de digitação no nome da classe (maiúsculas/minúsculas importam!)

Java é uma linguagem de tipagem forte e sensível a maiúsculas e minúsculas. Se sua classe se chama HelloWorld, mas você digita:

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

— a JVM não vai te entender. O nome da classe deve coincidir com o nome do arquivo exatamente. Sim, HelloWorld e helloworld são nomes diferentes para a JVM.

Cenário 3: Problemas com package (a armadilha mais traiçoeira)

Assim que você começa a usar pacotes (package), as regras do jogo mudam. Suponha que você tenha o arquivo:

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

Muitos iniciantes fazem assim:

cd src\njavac com/pythonlib/MyApp.java   // compilação bem-sucedida\njava MyApp                        // ERRO!

Por quê? Porque o nome completo da classe agora é com.pythonlib.MyApp, e não apenas MyApp. A JVM procura a classe pelo nome completo.