Archive Build Artifacts in Jenkins Pipelines (2026)

Jenkins pipelines often fail to archive build artifacts because the archiveArtifacts step is either misconfigured or not present, leading to lost build outputs and difficulty in debugging or redeploying.

Here’s a breakdown of common causes and their solutions:

1. Missing archiveArtifacts Step

Diagnosis: Review your Jenkinsfile. The archiveArtifacts step is a declarative directive within your post section or a specific stage. If it’s absent, Jenkins has no instruction to save artifacts.

Fix: Add the archiveArtifacts step to your Jenkinsfile. For example, to archive all files in the target/ directory:

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                // ... your build commands ...
            }
        }
    }
    post {
        success {
            archiveArtifacts artifacts: 'target/**'
        }
    }
}

Why it works: This explicitly tells Jenkins to collect files matching the specified pattern after the pipeline run completes successfully.

2. Incorrect artifacts Pattern

Diagnosis: The artifacts parameter uses Ant-style glob patterns. If the pattern is too broad, too narrow, or contains typos, it won’t match the files you intend to archive. Check the Jenkins console output for messages indicating no files were found for archiving.
Fix: Adjust the artifacts pattern to precisely match your build outputs. For instance, if your build produces JAR files in a build/libs/ directory:
```
post {
    success {
        archiveArtifacts artifacts: 'build/libs/*.jar'
    }
}
```
If you need to archive multiple types of files, use a comma-separated list or a more general pattern:
```
post {
    success {
        archiveArtifacts artifacts: 'build/libs/*.jar, build/reports/**/*.html'
    }
}
```
Why it works: The artifacts parameter is a filter; a correct pattern ensures that only the intended files are selected for archiving, preventing unnecessary disk usage and ensuring essential outputs are saved.

3. Archiving in the Wrong Pipeline Section

Diagnosis: The archiveArtifacts step is typically placed in the post section, specifically within success, failure, or always blocks. If it’s placed directly in a stage that doesn’t always run or if the stage fails before the archiving step, artifacts won’t be saved.

Fix: Ensure archiveArtifacts is within the post section of your Jenkinsfile for reliable execution.

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh './gradlew assemble'
            }
        }
        stage('Test') {
            steps {
                sh './gradlew test'
            }
        }
    }
    post {
        success {
            archiveArtifacts artifacts: 'build/libs/*.jar'
        }
        failure {
            archiveArtifacts artifacts: 'build/reports/tests/test/**' // Archive test reports on failure
        }
    }
}

Why it works: The post section is designed for actions that occur after the stages have executed, guaranteeing that archiving happens regardless of individual stage outcomes (depending on the post condition used).

4. Insufficient Disk Space on Jenkins Controller/Agent

Diagnosis: If the Jenkins controller or the agent where the build runs runs out of disk space, it cannot write the archived artifacts. Check the disk usage on your Jenkins nodes using df -h on Linux/macOS or Disk Management on Windows.
Fix: Free up disk space on the relevant Jenkins node or increase its storage capacity. For example, on Linux, you might remove old build artifacts or logs:
```
# Find and remove old log files larger than 1GB
find /var/log/jenkins/ -type f -size +1G -delete
```
Then, re-run the pipeline.
Why it works: Archiving requires physical storage. Ensuring sufficient free space allows Jenkins to persist the build artifacts.

5. Incorrect allowEmpty Setting

Diagnosis: By default, if the archiveArtifacts step finds no files matching the pattern, the build might be marked as unstable or fail, depending on Jenkins configuration. If you intend for artifacts to be optional, this setting is crucial.

Fix: Set allowEmpty: true if it’s acceptable for no artifacts to be archived for a particular build.

post {
    success {
        archiveArtifacts artifacts: 'nonexistent/path/*.log', allowEmpty: true
    }
}

Why it works: This flag tells Jenkins that it’s okay if the artifact pattern matches zero files, preventing the build from being incorrectly flagged as failed or unstable due to the absence of artifacts.

6. Network Issues or Agent Disconnection

Diagnosis: If the Jenkins agent is disconnected from the controller during or after the build, or if there are network interruptions, the archived artifacts might not be transferred to the controller’s artifact storage. Check Jenkins build logs for connection errors or agent status.
Fix: Ensure stable network connectivity between your Jenkins agents and the controller. If using distributed builds, verify the agent’s connection status in "Manage Jenkins" -> "Nodes". For transient network issues, a simple retry of the build might suffice.
Why it works: Artifacts are typically stored on the Jenkins controller after being collected from the agent. A broken communication channel prevents this transfer.

After ensuring all artifacts are correctly archived, the next common challenge is managing the sheer volume of stored artifacts, which can lead to disk space exhaustion on the Jenkins controller.