Handling Maven Invalid LOC Header Error

1. Introduction

Sometimes when a jar in our local Maven repo is corrupt, we’ll see the error: Invalid LOC Header.

In this tutorial, we’re going to learn when it happens and how to handle and even at times prevent it.

2. When Does “Invalid LOC Header” Occur?

Maven downloads a project’s dependencies into a known location on our filesystem called a local repository. Every artifact that Maven downloads is also accompanied by its SHA1 and MD5 checksum files:

The purpose of these checksums is to ensure the integrity of the associated artifacts. Since networks and file systems can fail, just like anything else, there are times when artifacts get corrupted, making the artifact contents not match the signature.

In these situations, Maven builds throw an “invalid LOC header” error.

The solution is to remove the corrupt jar from the repository. Let’s see a couple of ways.

3. Delete the Local Repository

A quick-fix for the error is to delete the whole Maven local repository and build the project again:

rm -rf ${LOCAL_REPOSITORY}

This will erase the local cache and re-download all the project dependencies – not very efficient.

Note that the default local repository is at ${user.home}/.m2/repository unless we specified it in our settings.xml <localRepository> tag. We can also find the local repository by the command: mvn help:evaluate -Dexpression=settings.localRepository

4. Find the Corrupt Jar

Another solution is to identify the specific corrupt jar and delete it from the local repository.

When we use the Maven output stacktrace command, it’ll contain the corrupt jar details when it fails to process it.

We can enable debug level logging by adding -X to the build command:

mvn -X package

The resulting stack trace will indicate the corrupted jar towards the end of the log. After identifying the corrupted jar, we can locate it in the local repository and delete it. Now upon build, Maven will retry downloading the jar.

Also, we can test the integrity of the archive with the zip -T command:

find ${LOCAL_REPOSITORY} -name "*.jar" | xargs -L 1 zip -T | grep error

5. Validate Checksums

The two solutions mentioned earlier will only force Maven to re-download the jar. Of course, the issue could occur again in future downloads. We can prevent that by configuring Maven to validate the checksum while downloading the artifact from remote repository.

We can add the –strict-checksums or -C option to the Maven command. This will cause Maven to fail the build if the computed checksum doesn’t match the value in checksum files.

There are two options, either to fail the build if checksums don’t match:

-C,--strict-checksums

or warn which is the default option:

-c,--lax-checksums

Today Maven requires the signature files while uploading artifacts to the central repository. But there might be artifacts in the central repository that don’t have the signature files, particularly the historic ones. That is why the default option is warn.

For a more permanent solution, we can configure checksumPolicy in Maven’s settings.xml file. This property specifies the behavior when verification of an artifact checksum fails. To avoid problems in the future, let’s edit our settings.xml file to fail the download when the checksum fails:

<profiles>
    <profile>
        <repositories>
            <repository>
                <id>codehausSnapshots</id>
                <name>Codehaus Snapshots</name>
                <releases>
                    <enabled>false</enabled>
                    <updatePolicy>always</updatePolicy>
                    <checksumPolicy>fail</checksumPolicy>
                </releases>
            </repository>
        </repository>
    </profile>
</profiles>

We’d, of course, need to do this for each of our configured repositories.

6. Conclusion

In this quick write-up, we’ve seen when an invalid LOC header error can occur and options for how to handle it.