Resolving java.util.zip.ZipException: invalid LOC header in Maven Project Deployment

Error Phenomenon Analysis

During Maven project builds, when executing the mvn install command, developers often encounter the java.util.zip.ZipException: invalid LOC header (bad signature) exception. This error typically occurs when the Maven Shade plugin attempts to create a shaded JAR file, indicating that one of the dependency JAR files is corrupted or has format issues.

Root Cause Investigation

From the error stack trace, it's evident that the exception occurs in the java.util.zip.ZipFile.read() method, indicating that Maven encountered problems while reading a specific JAR file. The LOC header (Local File Header) is a crucial component of the ZIP file format, and when its signature is invalid, it suggests the file may be corrupted, incompletely downloaded, or has format problems.

Solution Implementation

Based on best practices, the most effective solution involves using Maven commands to automatically detect and re-download corrupted dependencies. The specific steps are as follows:

First, execute the following Maven command:

mvn spring-boot:run

When the command encounters a corrupted JAR file during execution, Maven will throw specific exception information, clearly indicating which dependency file has issues. At this point, navigate to the local Maven repository directory (typically located at ~/.m2/repository or C:\Users\[username]\.m2\repository) and delete the corresponding corrupted JAR file.

Repeat the above command until all corrupted dependencies are identified and replaced. In practical cases, common corrupted dependencies include MySQL connectors, Jackson serialization libraries, AspectJ, and other frequently used components.

Configuration Optimization Recommendations

To prevent similar issues from recurring, it's recommended to optimize the Maven Shade plugin configuration. In the pom.xml file, add more stringent resource filtering and transformer configurations:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <filters>
                    <filter>
                        <artifact>*:*</artifact>
                        <excludes>
                            <exclude>META-INF/*.SF</exclude>
                            <exclude>META-INF/*.DSA</exclude>
                            <exclude>META-INF/*.RSA</exclude>
                        </excludes>
                    </filter>
                </filters>
            </configuration>
        </execution>
    </executions>
</plugin>

Preventive Measures

To prevent JAR file corruption issues, consider implementing the following measures: regularly clean the local Maven repository, use stable network environments for dependency downloads, configure Maven to use HTTPS protocol for repository access, and regularly update Maven versions and plugin versions. Additionally, in team development environments, it's recommended to use unified dependency management strategies to ensure all developers use the same versions of dependency libraries.

Technical Deep Dive

From a technical perspective, the LOC header in the ZIP file format contains critical information such as file compression methods, modification times, and CRC checksums. When this information is corrupted or mismatched, Java's ZIP processing library throws ZipException. Maven frequently reads and manipulates JAR files during the build process, and any file corruption will cause build failures. Understanding this mechanism helps developers quickly identify root causes when encountering similar issues.