The Jenkins build agent failed to upload build artifacts to the Jenkins controller because the controller rejected the upload request due to an invalid checksum.
This usually means the artifact files on the agent are corrupted or incomplete, or the controller’s artifact storage is in a bad state.
1. Agent Disk Space Exhausted
- Diagnosis: SSH into the Jenkins agent machine. Run
df -h. Check the partition where Jenkins stores its workspace and build artifacts. If it’s near 100% full, this is your problem. - Fix: Free up disk space. This could involve deleting old workspaces (
rm -rf /path/to/jenkins/workspace/*), clearing the Jenkins agent’s temporary directories (rm -rf /path/to/jenkins/agent/temp/*), or increasing the disk size of the agent’s volume. - Why it works: Jenkins needs free space to write artifacts before uploading. A full disk prevents this, leading to incomplete or zero-byte files that cause checksum mismatches.
2. Incomplete Artifact Transfer from Agent
- Diagnosis: On the agent, navigate to the build’s workspace (
/path/to/jenkins/workspace/your_job_name/build_number/). Check the size of the artifact files you expect to be uploaded. Compare this to the size reported by Jenkins in the build log (if available before the error) or by looking at the artifact’s size on the controller’s filesystem (if it partially uploaded). If the agent’s file size is significantly smaller or zero, the artifact wasn’t fully generated or copied to the archive location on the agent. - Fix: Ensure your build script correctly copies all intended artifacts to a designated artifact directory within the workspace before Jenkins attempts to archive them. For example, if your build uses
make, ensuremake installor a similar target places files inbuild/libs/or a similar predictable location. Then, configure Jenkins to archivebuild/libs/*. - Why it works: Jenkins archives files that exist at the time of the archive step. If the build process itself failed to create or place the files correctly, Jenkins will try to archive nothing, resulting in a checksum error when it expects data.
3. Network Interruption During Upload
- Diagnosis: Examine the Jenkins controller’s system logs (
/var/log/jenkins/jenkins.logor equivalent) and the agent’s logs for network-related errors (e.g., "connection reset," "broken pipe," "timeout"). Check network connectivity between the agent and controller usingpingandtraceroutefrom the agent to the controller’s IP/hostname. - Fix: Investigate and resolve network issues. This might involve checking firewalls, ensuring stable network routes, or restarting network interfaces on either the agent or controller. For persistent but intermittent issues, you might need to configure Jenkins to retry artifact uploads.
- Why it works: A dropped connection during the upload process means the artifact file on the controller is incomplete, leading to a checksum mismatch with what the agent claims to have uploaded.
4. Corrupted Artifacts on Agent Filesystem
- Diagnosis: On the agent, navigate to the build’s workspace (
/path/to/jenkins/workspace/your_job_name/build_number/). Re-run the build step that generates the artifact. Manually calculate the checksum of the generated artifact file usingmd5sum artifact.ziporsha256sum artifact.zip. Then, in Jenkins, configure a build step after artifact generation to explicitly calculate and print the checksum of the same file. Compare these checksums. If they differ, the file is corrupted. - Fix: If the artifact generation process is faulty, fix the build script. If the agent’s disk is experiencing I/O errors, investigate the underlying storage (e.g., check
dmesgfor disk errors, runfsckon the partition if unmounted). - Why it works: If the artifact file itself is damaged on the agent’s disk, its checksum will not match the checksum Jenkins calculates internally based on the data it receives, causing the upload to fail.
5. Jenkins Controller Artifact Storage Issues
- Diagnosis: On the Jenkins controller, navigate to the artifact storage directory for the specific build (
/var/lib/jenkins/jobs/your_job_name/builds/build_number/archive/). Check the integrity of existing artifact files. Try deleting a problematic artifact from the controller’s filesystem and triggering a re-run of the build on the agent. If the re-run succeeds, the original artifact on the controller was likely corrupted. - Fix: If artifacts on the controller are found to be corrupted, the most reliable fix is to clear out the old builds’ artifact directories on the controller. You can use Jenkins’ "Delete old builds" configuration to manage this, or manually remove directories under
/var/lib/jenkins/jobs/your_job_name/builds/that contain corrupted artifacts. - Why it works: The "Artifact Not Found" error can sometimes be a symptom of the controller’s copy of the artifact being damaged, not necessarily the one on the agent. Jenkins tries to verify the uploaded artifact against its own stored version or expected state.
6. Incorrect Artifact Archiving Configuration
- Diagnosis: In the Jenkins job configuration, go to "Post-build Actions" and check the "Archive the artifacts" setting. Ensure the pattern correctly matches the files and directories you intend to archive. Look for typos, incorrect wildcards, or paths that are relative to the wrong directory. For example, archiving
target/*.jaris correct iftargetis in the workspace root, but incorrect if it’s nested deeper. - Fix: Correct the artifact archiving pattern in the job configuration to accurately reflect the location of the generated artifacts within the build workspace.
- Why it works: A misconfigured pattern means Jenkins is told to archive files that don’t exist in the specified location, or it’s looking in the wrong place, leading to the controller not finding the expected files and subsequently failing the checksum validation.
7. Jenkins Controller Disk Full or Corrupted Artifacts Root
- Diagnosis: On the Jenkins controller, run
df -hto check the disk space for/var/lib/jenkins. If it’s full, Jenkins cannot write new artifacts or maintain its index. Also, check the permissions and ownership of/var/lib/jenkins/jobs/your_job_name/builds/build_number/archive/to ensure thejenkinsuser can write to it. - Fix: Free up disk space on the controller’s Jenkins home directory. If permissions are wrong, use
chown -R jenkins:jenkins /var/lib/jenkinsandchmod -R u+rwX /var/lib/jenkins. - Why it works: Jenkins needs write access and space in its primary data directory (
/var/lib/jenkins) to store build artifacts. A full disk or incorrect permissions will prevent this.
The next error you’ll likely encounter if you haven’t fixed the underlying issue is a "Build step 'Archive the artifacts' marked build as failure" or a similar explicit failure in the build log, rather than just an artifact not appearing.