GitLab-Runner: There has been a runner system failure, Job failed (system failure), prepare the environment: failed to start the process, exec: “pwsh”


The Shell executor is a simple executor that you use to execute builds locally on the machine where GitLab Runner is installed. It supports all systems on which the Runner can be installed. That means that it’s possible to use scripts generated for Bash, PowerShell Core, Windows PowerShell, and Windows Batch (deprecated). Like I said before, Shell is the simplest executor to configure. All required dependencies for your builds need to be installed manually on the same machine that GitLab Runner is installed on. Here are some related guides: How to install Git on macOS, How to uninstall Git on macOS, Practical Git use with mackdown, how to clone a repository and install software from GitHub on Windows, how to use AWS CodeCommit, Azure DevOps and GitHub integration for Docker and Kubernetes deployment, and how to build your first CI/CD Pipeline in Azure DevOps using ASP.Net Core Application.

The following error "There has been a runner system failure, please try again: RROR: Job failed (system failure): prepare environment: failed to start process: exec: "pwsh": executable file not found in %PATH%" can result because the pwsh entry for the shell attribute in gitlab-runner config.toml does not work in some WIN10 machines. You may also want to see "how to install, register and start GitLab Runner on Windows".

PowerShell Desktop Edition is the default shell when a new runner is registered on Windows using GitLab Runner 12.0-13.12. In 14.0 and later, the default is PowerShell Core Edition. PowerShell doesn’t support executing the build-in context of another user.


GitLab Runner supports certain shells. To select a shell, specify it in your config.toml file. For example. So I had to edit the confg.toml like follows.


Below is the syntax of the config.toml file that is currently being edited to resolve this issue.

concurrent = 1
check_interval = 0

  session_timeout = 1800

  name = "windows10 runner with Shell"
  url = ""
  token = "xxxxxxxxxxxxxxxxxx"
  executor = "shell"
  shell = "pwsh"

I had to replace the shell executor with the following shell = “powershell” as shown below. You may also see this official guide from Docker on how this was defined.


When this is done, GitLab-runner should reload automatically. Bt to be safe, just restart manually to ensure it takes effect.

gitlab-runner.exe restart

Alternatively, you can restart via the services.msc as shown below.


Note: Generally it’s unsafe to run tests with shell executors. The jobs are run with the user’s permissions (gitlab-runner) and can “steal” code from other projects that are run on this server. Use it only for running builds on a server you trust and own. Kindly refer to this guide for more information.

I hope you found this blog post helpful. If you have any questions, please let me know in the comment session.

Notify of

Inline Feedbacks
View all comments
Would love your thoughts, please comment.x