There has been a runner system failure: 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). As 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. In this article, you will learn how to fix there has been a runner system failure: failed to start the process exec “pwsh”. Here are some related articles: Linux containers: How to install LXC/LXD for container management, The executor requires OSType=windows, but Docker engine supports OStypelinux, and how to fix Error: cannot lock ref ‘refs/remotes/origin/windows’.

Why was the error “There has been a runner system failure, Job failed, prepare the environment: failed to start the process, exec: “pwsh” prompted?

The following error "There has been a runner system failure, please try again: ERROR: Job failed (system failure): prepare the 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“. And how to uninstall GitLab from your Windows device.

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.


Modify the Config.toml file

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.


Resolution: Replace the Shell Executor with PowerShell

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.


Here are some related VMware guides: How to create and delete a snapshot on VMware Workstation. How to extend a VM’s Hard Disk on VMware Workstation, and how to install Docker Desktop and register GitLab-Runner with Docker. How to Failure 5456: Unable to determine destination disk, partition, and how to install Windows Server 2022 on VMware Workstation.

Restart The GitLab Services

When this is done, GitLab-runner should reload automatically. But 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.

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.

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