Cómo corregir java.lang.UnsupportedClassVersionError: Guía completa

Entrenador de Python en Línea para Principiantes

Aprende Python fácilmente sin sobrecargarte de teoría. Resuelve tareas prácticas con verificación automática, recibe pistas y escribe código directamente en el navegador, sin instalar nada.

Start Course

Introducción: Una "máquina del tiempo" para tu código Java

Imagina: descargaste una biblioteca genial, escribiste algunas líneas de código, presionas "Run" — y en lugar de un programa funcionando, ves un mensaje largo y aterrador:

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

¿Te suena familiar? Si alguna vez te has encontrado con java.lang.UnsupportedClassVersionError, sabes que es como una conversación entre dos personas que hablan diferentes idiomas. Tu programa Java habla en la versión 61.0 (Java 17), pero el entorno de ejecución solo entiende hasta la versión 55.0 (Java 11).

En este tutorial, analizaremos qué es Unsupported major.minor version, por qué ocurre y, lo más importante, cómo solucionarlo. No solo te daremos soluciones listas, sino que te enseñaremos a entender la raíz del problema. ¡Vamos allá!

\n\n

¿Qué es major.minor version? Breve introducción

Cada archivo .class en Java tiene una etiqueta interna — major.minor version. Este es el número de versión del formato de bytecode que crea el compilador javac. Por ejemplo:

major 52 → Java 8
major 55 → Java 11
major 61 → Java 17
major 65 → Java 21

Cuando ejecutas una aplicación, el JRE (Java Runtime Environment) verifica si puede "entender" ese archivo. Si la versión del archivo es más reciente que la versión del JRE, obtienes java.lang.UnsupportedClassVersionError.

Una analogía simple: imagina que intentas abrir un documento PDF creado en Adobe Acrobat 2023 en Adobe Reader 2010. El programa te dirá: "No conozco este formato".

\n\n

Principales causas del error UnsupportedClassVersionError

El error Unsupported major.minor version puede ocurrir por varias razones:

Versiones diferentes de JDK y JRE: Compilaste el código con JDK 17, pero lo ejecutas en JRE 11.
Bibliotecas de terceros: Conectaste un archivo JAR compilado para Java 17, pero tu entorno de ejecución es Java 8.
Configuración incorrecta de Maven/Gradle: En el archivo de compilación se especifica una versión de Java, pero en el servidor está instalada otra.
Despliegue en un servidor antiguo: Desarrollas en un IDE moderno, pero el servidor de producción funciona con una versión obsoleta de Java.

\n\n

Tutorial paso a paso: cómo corregir el error

Analicemos los pasos concretos para resolver el problema. Consideraremos tres escenarios principales.

\n\n

Paso 1: Verifica las versiones de Java

Lo primero es entender quién es el "culpable". Abre la terminal y ejecuta:

# Versión con la que compilas (JDK)\njavac -version\n\n# Versión con la que ejecutas (JRE)\njava -version

Si no coinciden, esa es la causa. Por ejemplo, javac muestra "17.0.1" y java muestra "11.0.12".

Solución: Instala versiones iguales, ya sea actualizando el JRE o reduciendo la versión de compilación (más abajo se explica).

\n\n

Paso 2: Corregir la configuración de compilación

Si no puedes actualizar el JRE (por ejemplo, en el servidor), debes compilar el código para una versión más antigua. Usa las banderas -source y -target en el compilador:

// Compilamos código Java 17, pero generamos bytecode para Java 11\njavac -source 17 -target 11 MyApp.java

Importante: -source indica qué sintaxis de Java estás usando, y -target para qué versión de JRE generar el archivo .class. Si tu código usa características de Java 17 (por ejemplo, expresiones switch), se compilarán en bytecode compatible.