Maven y JARs locales: 5 errores fatales y su solución

¿Por qué "simplemente copiar el JAR en la carpeta" no funciona?

Cada desarrollador Java que se ha topado con Maven al menos una vez, tarde o temprano se encuentra con un muro: "Necesito conectar una biblioteca antigua que no está en Maven Central. ¿Qué hago?". Buscas en Google, encuentras una pregunta en Stack Overflow con miles de visitas, pruebas el primer consejo — y obtienes un ClassNotFoundException o Missing artifact.

¿Te suena familiar? En este artículo analizaremos los principales errores al agregar archivos JAR locales a un proyecto Maven y, lo más importante, cómo evitarlos. No solo aprenderás la teoría, sino que también verás código funcional que puedes aplicar de inmediato en tu proyecto Java.

Error n.º 1: System scope sin systemPath

La trampa más común para principiantes es agregar una dependencia con <scope>system</scope>, pero olvidar especificar <systemPath>. Maven intenta honestamente encontrar el JAR, pero no sabe dónde está.

Cómo se ve el error

[ERROR] Failed to execute goal on project my-app: \nCould not resolve dependencies for project com.example:my-app:jar:1.0: \nThe following artifacts could not be resolved: \ncom.example:my-custom-lib:jar:1.0 (absent)

Código incorrecto

<dependency>\n    <groupId>com.example</groupId>\n    <artifactId>my-custom-lib</artifactId>\n    <version>1.0</version>\n    <scope>system</scope>\n    <!-- ¡systemPath falta! -->\n</dependency>

Solución correcta

Siempre especifica la ruta completa al archivo JAR mediante <systemPath>. Es recomendable usar una ruta relativa desde la raíz del proyecto para no depender de una máquina de desarrollo específica.

<dependency>\n    <groupId>com.example</groupId>\n    <artifactId>my-custom-lib</artifactId>\n    <version>1.0</version>\n    <scope>system</scope>\n    <systemPath>${project.basedir}/libs/my-custom-lib-1.0.jar</systemPath>\n</dependency>

Importante: El archivo JAR debe estar en la carpeta libs/ dentro de tu proyecto. Créala si aún no lo has hecho.

Error n.º 2: Olvidar install-file para proyectos multimódulo

Supongamos que agregaste un JAR local mediante system scope y todo funciona localmente. Pero cuando intentas compilar el proyecto en un servidor CI (Jenkins, GitLab CI) — la compilación falla. ¿Por qué? Porque el system scope no se transmite transitivamente y no llega al repositorio local de Maven.

Enfoque correcto: instalar el JAR en el repositorio local

Usa el comando mvn install:install-file. Esto agregará tu JAR a ~/.m2/repository y estará disponible para todos los módulos del proyecto y para las compilaciones CI.

mvn install:install-file \\\n   -Dfile=libs/my-custom-lib-1.0.jar \\\n   -DgroupId=com.example \\\n   -DartifactId=my-custom-lib \\\n   -Dversion=1.0 \\\n   -Dpackaging=jar \\\n   -DgeneratePom=true

Después de esto, en pom.xml puedes especificar una dependencia normal sin systemPath:

<dependency>\n    <groupId>com.example</groupId>\n    <artifactId>my-custom-lib</artifactId>\n    <version>1.0</version>\n</dependency>

Error n.º 3: Usar URL file:// en repositorios

Algunos desarrolladores intentan "engañar" a Maven agregando una carpeta local como repositorio mediante <repository> con una URL file://. Técnicamente funciona, pero crea un montón de problemas:

\n
• Falta de portabilidad: la ruta /home/user/project/libs no funcionará en otra máquina.
\n
• Confusión con versiones:
\n