GitLab Runner "prepare environment: exit status 1": shell profile fixes
Short answer
"ERROR: Job failed: prepare environment: exit status 1" means the runner couldn't start the job's shell, before any of your script ran. With the shell executor, the runner starts a login shell as its user, usually gitlab-runner, so that user's profile files run before and after the job's script, and one of them failed. The classic cause is a ~/.bash_logout that runs clear_console, which fails without a terminal: comment it out. Other profile files, such as .bashrc, .condarc or .rvmrc, and SELinux can fail the same way. On Windows, "pwsh": executable file not found means PowerShell 7 isn't installed. On Kubernetes, prepare environment errors such as "timed out waiting for pod to start" mean the job's pod never started.
A job fails before any of its script runs, right after Preparing environment:
ERROR: Job failed: prepare environment: exit status 1. Check https://docs.gitlab.com/runner/shells/#shell-profile-loading for more information
Older runners link to shells/index.html, and some versions say Job failed (system failure). Either way, the runner couldn’t start the job’s shell. Here’s why, with GitLab Runner 19.5, and how to fix it on each kind of runner.
Which runner it is
| Executor | What failed | Most likely cause |
|---|---|---|
| Shell | The runner user’s login shell | A profile file, such as .bash_logout |
| SSH, VirtualBox, Parallels | The target machine’s login shell | Its profile files |
| Shell on Windows | Starting PowerShell | pwsh isn’t installed |
| Kubernetes | Creating or starting the job’s pod | The cluster, its API, or the image |
The job log’s first lines name the executor, such as Using Shell (bash) executor....
Shell runners: the profile files
The shell executor runs each job’s script through a login shell as the runner’s user, which is gitlab-runner when the runner is installed from the Linux packages. GitLab’s docs describe it as:
cat generated-bash-script | su --shell /bin/bash --login gitlab-runner
A login shell runs that user’s profile files first, and runs ~/.bash_logout when the script exits. If one of them fails, the job fails at Preparing environment.
.bash_logout and clear_console
The most common culprit, from Ubuntu’s and Debian’s default profile, is in /home/gitlab-runner/.bash_logout:
if [ "$SHLVL" = 1 ]; then
[ -x /usr/bin/clear_console ] && /usr/bin/clear_console -q
fi
clear_console fails without a terminal, which jobs don’t have. Comment the block out, then retry the job.
Find the file that fails
As root, pipe a small script into a login shell as the runner’s user. Like the runner’s own script, it sets set -e and ends with exit, which is when .bash_logout runs:
printf 'set -e\necho ok\nexit 0\n' | su --shell /bin/bash --login gitlab-runner
echo $?
An exit status other than 0 points at the profile, even when ok prints. Then check:
.bash_profile,.bashrcand.profilefor commands that callexit, read input or need a terminal. Any failure in.bash_logoutfails the job.- Tool hooks such as conda,
.condarc, and rvm,.rvmrc, which GitLab’s docs list as known to fail. - SELinux, which can block the runner’s commands. Look for denials with
sealert -a /var/log/audit/audit.log.
If the job works when you start the runner yourself with gitlab-runner run, but not as a service, compare the two users: the service runs jobs as the user given with --user.
SSH, VirtualBox and Parallels
These executors run the job through the target machine’s login shell, so the same profile files apply, on that machine. Over SSH, the message can say Process exited with status 1 instead. Fix the profile of the user the runner connects as.
Windows: pwsh not found
ERROR: Job failed (system failure): prepare environment: failed to start process: starting OS command: exec: "pwsh": executable file not found in %PATH%
Older runners leave out starting OS command:. New Windows runners use PowerShell 7, pwsh, as their shell. Install PowerShell 7 on the runner’s machine, or use Windows PowerShell instead, in the runner’s config.toml:
[[runners]]
shell = "powershell"
Kubernetes: the pod never starts
On Kubernetes, preparing the environment means creating the job’s pod and waiting for it, so the errors look different:
ERROR: Job failed (system failure): prepare environment: waiting for pod running: timed out waiting for pod to start (last phase: Pending)
timed out waiting for pod to start: the pod didn’t start within the runner’spoll_timeout, 180 seconds by default, for example because the cluster has too little CPU or memory to schedule it, or its image takes too long to pull. An image that can’t be pulled at all fails sooner, withimage pull failed. The job log shows the pod’s warning events. Fix the cause, or raisepoll_timeoutin[runners.kubernetes].context deadline exceeded, oretcdserver: request timed out: the cluster’s API server didn’t answer in time, usually because it’s overloaded.
Since GitLab Runner 19.0, prepare_timeout in [[runners]] caps the whole prepare stage; by default, it’s the job’s timeout.
On your phone
MergeBell shows a job’s log live, so a job that fails at Preparing environment stands out, and Retry reruns it on the free tier. The fix is on the runner’s machine, not in your repository, so once it’s in place, a retry works with no new commit. If jobs don’t start at all, see jobs stuck pending; more on retries in how to retry a failed GitLab pipeline.
Frequently asked questions
What does "prepare environment: exit status 1" mean in GitLab Runner?
The runner failed while preparing the job's environment, before your script started. With the shell executor, it starts a login shell as the runner's user, so that user's profile files run before and after the job's script; one of them failed. With the SSH, VirtualBox and Parallels executors, the target machine's profile runs instead.
How do I fix "prepare environment: exit status 1" on a shell runner?
Check the runner user's profile files, usually /home/gitlab-runner. The most common culprit is a .bash_logout that runs clear_console: comment out that block and retry the job. Then check .bash_profile, .bashrc and .profile for commands that call exit, read input or need a terminal, and tools such as conda or rvm that hook into the shell.
How can I test the GitLab runner user's shell profile?
As root, pipe a small script that ends like the runner's into a login shell as the runner's user: printf 'set -e\necho ok\nexit 0\n' | su --shell /bin/bash --login gitlab-runner, then echo $?. The set -e and exit lines matter, because .bash_logout runs only on exit and its failures count only with set -e. An exit status other than 0 points at the profile, even when ok prints.
Why does a Windows GitLab runner fail with "pwsh": executable file not found?
New Windows runners use PowerShell 7, pwsh, as their shell, and it isn't installed on that machine. Install PowerShell 7, or set shell = "powershell" in the runner's config.toml to use Windows PowerShell instead.
What does "prepare environment: timed out waiting for pod to start" mean on Kubernetes?
The job's pod didn't start within the runner's poll_timeout, 180 seconds by default. Usually the cluster couldn't schedule it, for lack of CPU or memory, or its image took too long to pull; an image that can't be pulled at all fails sooner, with image pull failed. The job log shows the pod's warning events. Fix the cause, or raise poll_timeout in the runner's [runners.kubernetes] section.
Sources
- GitLab Runner docs — Shell profile loading
- GitLab Runner docs — FAQ: Job failed (system failure): preparing environment
- GitLab Runner docs — Kubernetes executor troubleshooting
- GitLab Runner docs — Prepare stage timeout
- GitLab Runner source — the prepare environment error (build.go)
Checked against these pages on 13 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.