GitLab CI "could not start because it could not retrieve the needed artifacts" in CI

By Daniel Zoghalchali·Latchkey

A job that depends on artifacts from an earlier job cannot start because those artifacts are unavailable: the producing job did not create them, they expired, or the dependencies/needs wiring is wrong.

What this error means

The job fails immediately with "This job could not start because it could not retrieve the needed artifacts." It never runs your script.

This job could not start because it could not retrieve the needed artifacts.
Please check the job log for more information.

Common causes

The upstream job did not produce the artifacts

The producing job has no matching artifacts:paths, or it failed before uploading, so there is nothing to download.

The artifacts expired before this job ran

A short artifacts:expire_in removed the files before the dependent job retrieved them.

How to fix it

Ensure the producer uploads, and wire needs:artifacts

1. Confirm the upstream job declares the artifacts the consumer needs.
2. Reference it via needs with artifacts: true.
3. Set a long enough expire_in so they survive until consumed.

build:
  stage: build
  artifacts:
    paths: [dist/]
    expire_in: 1 day

deploy:
  stage: deploy
  needs:
    - job: build
      artifacts: true

Extend artifact retention

If artifacts expire too early for the downstream job, increase expire_in on the producing job.

artifacts:
  paths: [dist/]
  expire_in: 1 week

How to prevent it

• Match consumer needs/dependencies to producer artifact paths.
• Set expire_in long enough to outlive every dependent job.
• Fail fast if a producer job stops emitting expected artifacts.

Frequently asked questions

Related guides

References

• GitHub Actions documentation