ARTIFACTORY: Debugging Checksum Mismatch Errors

Scott Mosher
2023-01-22 11:07

This article will go over a handful of ways to further debug when receiving a client checksum mismatch error.  This will not cover all causes as different clients handle checksums differently but will focus on the general debug process when receiving this error.  

To start, a checksum mismatch error means the client received an artifact with an unexpected checksum.  This should always output within the client the expected checksum along with the actual checksum.  

Debugging Steps to Take

Most, if not all, occurrences of this error will have a remote repository involved.  We first will want to perform a checksum search within Artifactory for both actual and expected checksum output within the error.  We will want to see if the “same” artifact is referenced in multiple repositories within the Artifactory instance.  

The initial configuration to check is around any virtual repositories containing the artifact in multiple repositories that have different checksums.  We can look into the resolution order of the virtual repository to better understand the reasoning around the binary getting returned

Different Scenarios to Consider

We will provide a few specific examples outlining the most common causes of this error:

1.   A user downloads an artifact from a remote repository, makes a simple change to the binary and redeploys to a local repository.  In this case, we have the artifact within a local repository and a remote repository, all contained within a single virtual.  A virtual will not and cannot save multiple checksums for the artifact.  Depending on the client, we may run into issues where the client expects the public package from the remote repository but due to the virtual resolution order, the local repository is returning an unexpected binary/checksum.

Solution/workaround: This would be considered bad practice to change a binary without updating the version.  Depending on the binary we want to return, we can either clear the cache and generate updated metadata for the virtual or rename the local package to increase/update the version.

2.   A single remote repository has pulled and cached the package.  We store this artifact locally and a change was made to the artifact on the remote registry.  In this case, the metadata we pull from the remote registry will have a checksum that differs from the locally cached package. 

Solution/workaround: In this case, we need to remove the cached binary so Artifactory will reach back out to the remote registry to pull the updated package.

3.   A virtual has multiple remote repositories where the same package and version exist on both of these remote registries with different checksums.  A simple example of this can be seen from the 2 links:

Here, we see the linux-64/_libgcc_mutex-0.1-main.tar.bz2 is the “same” binary, but the checksum differs.  This can cause issues in Artifactory depending on the resolution order and the cache.  A virtual repository will look within the local repositories first, then the remote-cache repositories and lastly will reach out through the remote repositories to the remote endpoints.  If the package we expect is not cached and the other binary is already cached in the other repository, we can see the checksum mismatch.  

Solution/workaround: Setting the “Priority Resolution” for a specific remote repository will workaround this issue.  The “Priority Resolution” means it will search the remote endpoint for this repository prior to looking at the other repository's cache.  This can be set within the Advanced tab of the remote repository configuration.

There are many other causes, some specific to the package type, and if we run into the checksum mismatch error that does not align with the above examples, open a case with the JFrog Support Team to further dig into other possible causes.