Troubleshooting job artifacts

When working with job artifacts, you might encounter the following issues.

Job does not retrieve certain artifacts

By default, jobs fetch all artifacts from previous stages, but jobs using dependencies or needs do not fetch artifacts from all jobs by default.

If you use these keywords, artifacts are fetched from only a subset of jobs. Review the keyword reference for information on how to fetch artifacts with these keywords:

Job artifacts use too much disk space

If job artifacts are using too much disk space, see the job artifacts administration documentation.

Error message No files to upload

This message appears in job logs when a the runner can’t find the file to upload. Either the path to the file is incorrect, or the file was not created. You can check the job log for other errors or warnings that specify the filename and why it wasn’t generated.

For more detailed job logs, you can enable CI/CD debug logging and try the job again. This logging might provide more information about why the file wasn’t created.

Error message Missing /usr/bin/gitlab-runner-helper. Uploading artifacts is disabled.

Introduced in GitLab 15.2, GitLab Runner uses RUNNER_DEBUG instead of DEBUG, fixing this issue.

In GitLab 15.1 and earlier, setting a CI/CD variable named DEBUG can cause artifact uploads to fail.

To work around this, you can:

  • Update to GitLab and GitLab Runner 15.2
  • Use a different variable name

  • Set it as an environment variable in a script command:

    failing_test_job:  # This job might fail due to issue gitlab-org/gitlab-runner#3068
  variables:
    DEBUG: true
  script: bin/mycommand
  artifacts:
    paths:
      - bin/results

successful_test_job:  # This job does not define a CI/CD variable named `DEBUG` and is not affected by the issue
  script: DEBUG=true bin/mycommand
  artifacts:
    paths:
      - bin/results

Error message FATAL: invalid argument when uploading a dotenv artifact on a Windows runner

The PowerShell echo command writes files with UCS-2 LE BOM (Byte Order Mark) encoding, but only UTF-8 is supported. If you try to create a dotenv artifact with echo, it causes a FATAL: invalid argument error.

Use PowerShell Add-Content instead, which uses UTF-8:

test-job:
  stage: test
  tags:
    - windows
  script:
    - echo "test job"
    - Add-Content -Path build.env -Value "MY_ENV_VAR=true"
  artifacts:
    reports:
      dotenv: build.env

Job artifacts do not expire

If some job artifacts are not expiring as expected, check if the Keep artifacts from most recent successful jobs setting is enabled.

When this setting is enabled, job artifacts from the latest successful pipeline of each ref do not expire and are not deleted.

Error message This job could not start because it could not retrieve the needed artifacts.

A job configured with the needs:artifacts keyword fails to start and returns this error message if:

  • The job’s dependencies cannot be found.
  • The job cannot access the relevant resources due to insufficient permissions.

The troubleshooting steps to follow differ based on the syntax the job uses:

For a job configured with needs:project

The could not retrieve the needed artifacts. error can happen for a job using needs:project with a configuration similar to:

rspec:
  needs:
    - project: my-group/my-project
      job: dependency-job
      ref: master
      artifacts: true

To troubleshoot this error, verify that:

  • Project my-group/my-project is in a group with a Premium subscription plan.
  • The user running the job can access resources in my-group/my-project.
  • The project, job, and ref combination exists and results in the desired dependency.
  • Any variables in use evaluate to the correct values.

For a job configured with needs:pipeline:job

The could not retrieve the needed artifacts. error can happen for a job using needs:pipeline:job with a configuration similar to:

rspec:
  needs:
    - pipeline: $UPSTREAM_PIPELINE_ID
      job: dependency-job
      artifacts: true

To troubleshoot this error, verify that:

  • The $UPSTREAM_PIPELINE_ID CI/CD variable is available in the current pipeline’s parent-child pipeline hierarchy.
  • The pipeline and job combination exists and resolves to an existing pipeline.
  • dependency-job has run and finished successfully.