GitLab CI artifacts: no matching files, expired artifacts, and fixes
Short answer
When a GitLab CI job's artifacts go missing, the job log usually says why. "no matching files" means an artifacts:paths entry matched nothing in the project directory, $CI_PROJECT_DIR, and "No files to upload" means no path matched anything. A failed job uploads none of its artifacts:paths unless artifacts:when is always or on_failure; reports upload either way. Later jobs get artifacts from every earlier stage by default, but dependencies and needs narrow that, and a job stops with "could not retrieve the needed artifacts" when they expired or were never made. Artifacts expire after 30 days by default, except the latest ones on each branch. GitLab.com allows 1 GB per artifact archive; GitLab Self-Managed defaults to 100 MB.
A job finished, but its artifacts aren’t there: the next job can’t find the build, or the job page has nothing to download. The job log usually says why. Here is what each message means in GitLab 19.5 and the fix for it.
What the job log says
| The job says | What it means |
|---|---|
no matching files |
An artifacts:paths entry matched nothing. See paths. |
No files to upload |
No path matched anything, so the runner uploaded nothing. |
FATAL: too large |
GitLab refused the upload with HTTP 413: the archive is over the size limit. See size. |
| This job could not start because it could not retrieve the needed artifacts. | A job this one depends on has no artifacts left: they expired, were never made, or you can’t access them. See passing artifacts. |
FATAL: invalid argument, for a dotenv report on Windows |
PowerShell’s echo writes UCS-2 with a byte order mark, which the upload rejects. Write the file with Add-Content, which uses UTF-8. |
If the pipeline fails at once, with no jobs, and GitLab says jobs:build config contains unknown keys: artifact, the keyword is misspelled: see GitLab CI “configuration is invalid”.
Paths start at the project directory
WARNING: dist/: no matching files. Ensure that the artifact path is relative to the working directory (/builds/group/project)
ERROR: No files to upload
artifacts:paths are relative to the project directory, $CI_PROJECT_DIR, and can’t point outside it. A tool that writes to /tmp or your home folder leaves nothing to upload. Copy the files in, and check what’s really there:
build:
script:
- make
- ls -la dist/
artifacts:
paths:
- dist/
- Globs work, such as
reports/*.xmlor**/coverage.xml. - Directories upload with everything in them.
- Without
artifacts:name, the download is calledartifacts.zip.
GitLab Pages publishes from a job’s artifacts too: see GitLab Pages not working.
Failed jobs skip their paths by default
artifacts:when defaults to on_success: a failed job uploads none of its artifacts:paths, often exactly when you need its logs or screenshots. Reports under artifacts:reports, such as JUnit, upload either way. Change it for the paths:
test:
script: make test
artifacts:
when: always # or on_failure
paths:
- test-results/
always still uploads nothing when a job times out.
Passing artifacts between jobs
- By default, a job downloads the artifacts of every job in earlier stages.
dependencieslimits that to the jobs it lists, all in earlier stages;dependencies: []downloads none.needsdownloads only the artifacts of the jobs it needs. Addartifacts: falseto aneedsentry to skip them. To get artifacts from a job in the same stage, you must useneeds.- Don’t combine
dependenciesandneedsin one job.
When a needed job’s artifacts are gone, the job fails to start:
This job could not start because it could not retrieve the needed artifacts.
GitLab’s docs list three causes: the dependency wasn’t found, its artifacts expired, or you don’t have access. With needs:project, from another project, also check that the project is on Premium or Ultimate, that you have at least the Reporter role there, and, with a CI/CD job token, that your project is on its allowlist: see CI_JOB_TOKEN access to another project.
When artifacts expire
expire_insets the lifetime, likeexpire_in: 1 week. Without it, the instance’s Default artifacts expiration applies: 30 days, unless an administrator changed it.- The latest artifacts stay. For each branch and tag, GitLab keeps the artifacts of the latest pipeline, even a failed one, and of the latest successful one, whatever
expire_insays, while Keep artifacts from most recent successful jobs is on, as it is by default. Older pipelines’ artifacts start expiring once a newer pipeline on that branch succeeds, fails, is canceled or skipped, or stops at a manual job. - Keep: select it on a job’s page to stop that job’s artifacts from expiring.
The latest artifacts move with each new pipeline, so don’t link to them as a release. GitLab’s docs suggest a versioned package instead.
Size limits
Over the limit, the runner’s Uploading artifacts as "archive" to coordinator... line gets HTTP status 413, and the job ends with FATAL: too large. The limit applies to each artifact archive, not each file:
- GitLab.com: 1 GB compressed.
- GitLab Self-Managed and GitLab Dedicated: 100 MB by default. An administrator can change it for the instance, a group or a project.
Some report types have lower limits. To fit, list only the paths later jobs need, skip files with artifacts:exclude, or split the output across several jobs, each with its own limit. Dependencies you can download again, like npm packages, belong in the cache instead.
Download artifacts
-
From the job’s page: Download, or Browse to look inside the archive first. Pipeline and job lists have a Download artifacts button too.
-
The latest from a branch, from its latest successful pipeline, without looking up a job ID:
https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=buildReplace
/downloadwith/raw/path/to/fileto get a single file.
On your phone
MergeBell shows a job’s log live, so the “no matching files” warning is there as soon as the runner writes it, and Retry reruns a job on the free tier. A retry runs the same commit, so it helps when the fix is outside the repository, such as a raised size limit; a fix to .gitlab-ci.yml or the code needs a new commit. Downloading and browsing artifacts needs GitLab in a browser. Retrying well is in how to retry a failed GitLab pipeline.
Frequently asked questions
Why does GitLab say "no matching files" for my artifacts?
The runner looked for an artifacts:paths entry relative to the project directory, $CI_PROJECT_DIR, and found nothing. Either the file wasn't created, it was written somewhere else, such as /tmp, or the path or glob doesn't match. Add an ls to the job's script to see what's really there, and copy the files into the project directory if they're elsewhere.
Why are my GitLab artifacts missing when the job fails?
artifacts:when defaults to on_success, so a failed job uploads none of its artifacts:paths files. Only artifacts:reports, such as JUnit reports, upload whatever the result. Set when: always to upload the paths whether the job passes or fails, though not when it times out, or when: on_failure to upload them only when it fails, for example HTML test output and screenshots.
Why can't a later job see my GitLab artifacts?
By default a job downloads the artifacts of every job in earlier stages, but dependencies and needs change that. With dependencies it gets only the listed jobs' artifacts, and dependencies: [] gets none. With needs it gets only the needed jobs' artifacts, unless artifacts: false. Artifacts from a job in the same stage are only available through needs.
How long does GitLab keep job artifacts?
Until artifacts:expire_in runs out, or, without it, the instance's default expiration, 30 days unless an administrator changed it. The latest pipeline on each branch or tag, and the latest successful one, keep their artifacts regardless while Keep artifacts from most recent successful jobs is on, which it is by default. Select Keep on a job's page to stop its artifacts expiring.
How do I download the latest artifacts from a branch?
Use the job's page, or this API address, which points at that job in the branch's latest successful pipeline: https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/<branch>/download?job=<job-name>. Add /raw/<path> after the branch, instead of /download, to get a single file.
Sources
- GitLab docs — Job artifacts
- GitLab docs — Troubleshooting job artifacts
- GitLab docs — artifacts keyword
- GitLab docs — dependencies keyword
- GitLab docs — needs:artifacts keyword
- GitLab docs — Default artifacts expiration
- GitLab Runner source — the no matching files warning (file_archiver.go)
Checked against these pages on 2 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.
Do this from your phone with MergeBell
Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.
Get MergeBell for iPhoneGet MergeBell for Android
On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.