GitLab "Job failed (system failure): preparing 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/environment, not your code.

What this error means

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

ERROR: Job failed (system failure): preparing 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 shell profile. A profile that errors or prints to stderr (e.g. a broken .bashrc) fails environment preparation.

Executor/host transient problem

A Docker/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

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

Retry transient executor failures

When the cause is a momentary executor/host hiccup, an automatic retry on system failure recovers it.

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/host health (Docker daemon, node pressure).

Related guides