Como corrigir java.lang.UnsupportedClassVersionError: Guia completo

Introdução: Uma "máquina do tempo" para seu código Java

Imagine: você baixou uma biblioteca incrível, escreveu algumas linhas de código, clica em "Executar" — e em vez de um programa funcionando, vê uma mensagem longa e assustadora:

Exception in thread "main" java.lang.UnsupportedClassVersionError: \ncom/example/MyApp has been compiled by a more recent version of the Java Runtime \n(class file version 61.0), this version of the Java Runtime only recognizes \nclass file versions up to 55.0

Familiar? Se você já encontrou o java.lang.UnsupportedClassVersionError, sabe que é como uma conversa entre duas pessoas em idiomas diferentes. Seu programa Java fala na versão 61.0 (Java 17), mas o ambiente de execução entende apenas até a versão 55.0 (Java 11).

Neste tutorial, vamos analisar o que é Unsupported major.minor version, por que ele ocorre e, o mais importante, como corrigi-lo. Não vamos apenas dar soluções prontas, mas ensinar você a entender a raiz do problema. Vamos lá!

O que é major.minor version? Uma breve explicação

Cada arquivo .class em Java tem uma etiqueta interna — a major.minor version. Este é o número da versão do formato bytecode criado pelo compilador javac. Por exemplo:

\n
• major 52 → Java 8
\n
• major 55 → Java 11
\n
• major 61 → Java 17
\n
• major 65 → Java 21
\n

Quando você executa um aplicativo, o JRE (Java Runtime Environment) verifica se consegue "entender" esse arquivo. Se a versão do arquivo for mais recente que a versão do JRE, você recebe o java.lang.UnsupportedClassVersionError.

Uma analogia simples: imagine que você está tentando abrir um documento PDF criado no Adobe Acrobat 2023 no Adobe Reader 2010. O programa dirá: "Não conheço este formato".

Principais causas do erro UnsupportedClassVersionError

O erro Unsupported major.minor version pode ocorrer por vários motivos:

\n
• Versões diferentes de JDK e JRE: Você compilou o código no JDK 17, mas está executando no JRE 11.
\n
• Bibliotecas de terceiros: Você adicionou um arquivo JAR compilado para Java 17, mas seu ambiente de execução é Java 8.
\n
• Configuração incorreta do Maven/Gradle: O arquivo de build especifica uma versão do Java, mas o servidor tem outra instalada.
\n
• Implantação em servidor antigo: Você desenvolve em uma IDE moderna, mas o servidor de produção executa um Java desatualizado.
\n

Tutorial passo a passo: como corrigir o erro

Vamos detalhar etapas específicas para resolver o problema. Abordaremos três cenários principais.

Passo 1: Verifique as versões do Java

Primeiro, você precisa entender quem é o "culpado". Abra o terminal e execute:

# Versão na qual você compila (JDK)\njavac -version\n\n# Versão na qual você executa (JRE)\njava -version

Se elas não coincidirem — aí está a causa. Por exemplo, javac mostra "17.0.1" e java mostra "11.0.12".

Solução: Instale versões iguais, ou atualize o JRE, ou reduza a versão de compilação (mais sobre isso abaixo).

Passo 2: Corrija as configurações de compilação

Se você não puder atualizar o JRE (por exemplo, no servidor), precisa compilar o código para uma versão mais antiga. Use as flags -source e -target no compilador:

// Compila código Java 17, mas gera bytecode para Java 11\njavac -source 17 -target 11 MyApp.java

Importante: -source indica qual sintaxe Java você está usando, e -target — para qual versão do JRE gerar o arquivo .class. Se seu código usa recursos do Java 17 (por exemplo, expressões switch), eles serão compilados em bytecode compatível.