Fix GitLab CI Artifacts Not Found After Job Completion (2026)

The GitLab CI runner is failing to upload artifacts because the artifacts.reports path is being interpreted as a file instead of a directory.

Common Causes and Fixes:

Incorrect artifacts.reports Path:
- Diagnosis: Review your .gitlab-ci.yml file for the artifacts.reports section. Ensure the specified path points to a directory that actually exists and contains files to be uploaded. A common mistake is using a path that is a single file or a non-existent directory.
- Fix:
```
artifacts:
  reports:
    junit: "test-results/junit.xml" # Example of a file
```
  should be:
```
artifacts:
  reports:
    junit: "test-results/" # Example of a directory
```
  If junit.xml is the actual report, the path should point to the directory containing it, or the reports section should be used for specific report types like junit and point to the file.
- Why it works: The artifacts.reports directive is designed to collect specific types of reports (like JUnit XML) from a given path. If the path is a file, it might be treated as a single artifact, but the reports keyword implies a collection or a specific format that expects a directory. If you intend to upload a single file, use the general artifacts: paths: directive.
Permissions Issues on Runner:
- Diagnosis: The user running the GitLab Runner process on the host machine might not have write permissions to the directory where artifacts are staged before upload, or to the temporary directory used by the runner. Check the runner’s working directory and the output of ls -ld /path/to/runner/working/dir and ls -ld /tmp.
- Fix: Grant the runner user appropriate permissions. For example, if your runner is run by the user gitlab-runner:
```
sudo chown -R gitlab-runner:gitlab-runner /path/to/runner/working/dir
sudo chmod -R u+w /path/to/runner/working/dir
sudo chmod -R u+w /tmp # Or a more specific temporary directory if configured
```
- Why it works: The runner needs to be able to create, write to, and read from the artifact staging directories. Insufficient permissions prevent it from collecting and preparing the artifacts for upload.
Disk Space Full on Runner:
- Diagnosis: The runner’s disk where it stages artifacts might be full. Check disk usage with df -h. Look for partitions that are at or near 100% capacity, especially those corresponding to /var/lib/gitlab-runner or any custom build directories.
- Fix: Free up disk space by deleting old build artifacts, logs, or other unnecessary files. If this is a recurring issue, consider increasing the disk size or configuring artifact cleanup policies.
```
# Example: Clean up old artifacts if they are stored in /var/lib/gitlab-runner/cache
sudo find /var/lib/gitlab-runner/cache -type f -mtime +7 -delete
```
- Why it works: Artifacts are temporarily stored on the runner’s filesystem before being uploaded to GitLab. If there’s no space to write these temporary files, the upload process will fail.
Incorrect artifacts:expire_in Value:
- Diagnosis: While less common for "not found" errors, an incorrectly formatted expire_in value can sometimes cause unexpected behavior or prevent artifact processing. Ensure the format is correct (e.g., 1 week, 3 days, 2 hours).
- Fix: Correct the expire_in format. For example, change expire_in: 24h to expire_in: 1 day.
```
artifacts:
  paths:
    - build/
  expire_in: 1 week
```
- Why it works: The expire_in directive is used by GitLab to manage artifact storage. While invalid formats usually result in a different error, malformed values can sometimes lead to the artifact pipeline being prematurely discarded or not registered correctly by the GitLab backend.
Runner Configuration Issues (config.toml):
- Diagnosis: Check the runner’s config.toml file (usually located at /etc/gitlab-runner/config.toml or ~/.gitlab-runner/config.toml). Look for any settings related to artifact caching or temporary directories that might be misconfigured or pointing to non-existent locations.
- Fix: Ensure paths like builds_dir and cache_dir (if used for artifacts) are valid and writable by the runner user.
```
# Example config.toml snippet
[[runners]]
  name = "my-runner"
  url = "https://gitlab.com/"
  token = "..."
  executor = "docker"
  [runners.docker]
    # ...
  builds_dir = "/home/gitlab-runner/builds" # Ensure this directory exists and is writable
  cache_dir = "/home/gitlab-runner/cache"   # Ensure this directory exists and is writable
```
- Why it works: The runner’s config.toml defines its operational environment. If crucial directories for staging artifacts are incorrectly specified or inaccessible, the runner cannot function properly.
GitLab Server-Side Issues (Less Common):
- Diagnosis: If multiple jobs across different runners and projects are experiencing this, it might indicate a problem with the GitLab instance itself. Check the GitLab status page or logs on the GitLab server (/var/log/gitlab/gitlab-rails/production.log or similar). Look for errors related to artifact storage or object storage.
- Fix: This typically requires intervention from GitLab administrators. It might involve restarting GitLab services, checking object storage configuration (if using S3, GCS, etc.), or applying GitLab patches.
- Why it works: The GitLab backend is responsible for receiving and storing artifacts from runners. If the server is unhealthy or misconfigured, artifact uploads will fail.
Corrupted artifacts.zip:
- Diagnosis: Sometimes, the artifact zip file itself can become corrupted during the staging process on the runner. This is hard to diagnose directly from CI logs but can be inferred if other causes are ruled out.
- Fix: Try cleaning the runner’s cache or temporary build directories. A simple git clean -fdx in the project directory before building can sometimes resolve issues caused by stale or corrupted build outputs that are then included in artifacts.
- Why it works: Corrupted output files that are supposed to be artifacted can lead to an unprocessable artifact archive. Cleaning the workspace ensures a fresh build.

The next error you’ll likely hit after fixing artifact issues is a job failed status due to a missing artifacts.reports file, even though you’ve corrected the path.