Maven e JARs locais: 5 erros fatais e suas soluções

Por que "apenas copiar o JAR para a pasta" não funciona?

Todo desenvolvedor Java que já lidou com Maven, mais cedo ou mais tarde, encontra uma barreira: "Preciso conectar uma biblioteca antiga que não está no Maven Central. O que fazer?". Você pesquisa, encontra uma pergunta no Stack Overflow com milhares de visualizações, tenta o primeiro conselho — e recebe um ClassNotFoundException ou Missing artifact.

Familiar? Neste artigo, vamos analisar os principais erros ao adicionar arquivos JAR locais em um projeto Maven e, principalmente, como evitá-los. Você aprenderá não apenas a teoria, mas também verá código funcional que pode aplicar imediatamente no seu projeto Java.

Erro nº1: System scope sem systemPath

A armadilha mais comum para iniciantes — adicionar uma dependência com <scope>system</scope>, mas esquecer de especificar <systemPath>. O Maven tenta honestamente encontrar o JAR, mas não sabe onde ele está.

Como o erro se apresenta

[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 incorreto

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

Solução correta

Sempre especifique o caminho completo para o arquivo JAR através de <systemPath>. É recomendável usar um caminho relativo a partir da raiz do projeto, para não depender de uma máquina de desenvolvedor 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: O arquivo JAR deve estar na pasta libs/ dentro do seu projeto. Crie-a se ainda não o fez.

Erro nº2: Esqueceu do install-file para projetos multimódulo

Suponha que você adicionou um JAR local via system scope, e tudo funciona localmente. Mas quando tenta compilar o projeto no servidor CI (Jenkins, GitLab CI) — a compilação falha. Por quê? Porque o system scope não é transmitido transitivamente e não entra no repositório local do Maven.

Abordagem correta: instalar o JAR no repositório local

Use o comando mvn install:install-file. Isso adicionará seu JAR em ~/.m2/repository, e ele ficará disponível para todos os módulos do projeto e para compilações 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

Depois disso, no pom.xml você pode especificar uma dependência normal sem systemPath:

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

Erro nº3: Uso de URL file:// em repositórios

Alguns desenvolvedores tentam "enganar" o Maven adicionando uma pasta local como repositório através de <repository> com URL file://. Tecnicamente funciona, mas cria vários problemas:

\n
• Não portabilidade: o caminho /home/user/project/libs não funcionará em outra máquina.
\n
• Confusão com versões:
\n