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