Maven and Local JARs: 5 Fatal Errors and Their Solutions

Why "just copy the JAR into a folder" doesn't work?

Every Java developer who has ever dealt with Maven eventually hits a wall: "I need to include an old library that isn't in Maven Central. What do I do?". You Google it, find a Stack Overflow question with thousands of views, try the first piece of advice — and get a ClassNotFoundException or Missing artifact.

Sound familiar? In this article, we'll break down the top errors when adding local JAR files to a Maven project and, most importantly, how to avoid them. You'll learn not just the theory but also see working code you can immediately apply in your Java project.

Error #1: System scope without systemPath

The most common pitfall for beginners is adding a dependency with <scope>system</scope> but forgetting to specify <systemPath>. Maven honestly tries to find the JAR but doesn't know where it is.

What the error looks like

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

Incorrect code

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

Correct solution

Always specify the full path to the JAR file via <systemPath>. It is advisable to use a relative path from the project root to avoid being tied to a specific developer's machine.

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

Important: The JAR file must be in the libs/ folder inside your project. Create it if you haven't already.

Error #2: Forgot about install-file for multi-module projects

Let's say you added a local JAR via system scope, and everything works locally. But when you try to build the project on a CI server (Jenkins, GitLab CI) — the build fails. Why? Because system scope is not transitive and does not get into the local Maven repository.

The correct approach: installing the JAR into the local repository

Use the mvn install:install-file command. This will add your JAR to ~/.m2/repository, and it will be available for all project modules and CI builds.

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

After this, in pom.xml you can specify a regular dependency without systemPath:

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

Error #3: Using file:// URLs in repositories

Some developers try to "trick" Maven by adding a local folder as a repository via <repository> with a file:// URL. Technically it works, but it creates a bunch of problems:

\n
• Non-portability: the path /home/user/project/libs won't work on another machine.
\n
• Version confusion: [truncated]
\n