GitLab "Job failed (system failure): prepare environment"

The runner failed while setting up the job - before a single line of your script ran. "system failure" means the problem is in the executor or environment, not your code.

What this error means

The job fails almost instantly with "Job failed (system failure): prepare environment" and no script output. It is often intermittent and tied to one runner or executor.

gitlab-ci

ERROR: Job failed (system failure): prepare environment:
exit status 1. Check https://docs.gitlab.com/runner/shells/#shell-profile-loading for more information

Common causes

Shell profile loading fails

For the shell executor the runner sources the user's profile. A .bashrc that errors or writes to stderr at login fails environment preparation.

Executor or host transient problem

A Docker or Kubernetes executor that briefly cannot create the container, mount volumes, or reach the host runtime fails in the prepare stage - often transient.

How to fix it

Fix the runner shell profile

On a shell-executor runner, check the gitlab-runner user's .bashrc/.bash_profile for errors.
Remove commands that exit non-zero or write to stderr during login.
Re-run the job; preparation should pass.

Retry transient executor failures

When the cause is a momentary executor hiccup, an automatic retry on system failure recovers it. If you run on GitHub Actions, self-healing managed runners such as Latchkey auto-retry this class of transient infrastructure failure for you.

.gitlab-ci.yml

default:
  retry:
    max: 2
    when:
      - runner_system_failure

How to prevent it

Keep the gitlab-runner user's shell profile minimal and non-failing.
Add retry: when: runner_system_failure for flaky infrastructure.
Monitor executor and host health (Docker daemon, node pressure).