What is the Sitecore Docker “failed to solve: rpc error”?
You usually only see major docker problems the first time you are bringing up your Sitecore environment. So it's probably pretty likely that you came across this error while doing exactly this. This is a configuration error, flagging something is incorrectly configured either on your system or in Docker.
I'll go over some common ways to fix it in this article, and hopefully one of them will help you solve your problem.
Error:
failed to solve: rpc error: code = Unknown desc = failed to solve with frontend
dockerfile.v0: failed to create LLB definition: no match for platform in manifest
sha256:d96a6c2108e1449c872cc2b224a9b3444fa1415b4d6947280aba2d2bb3bd0025: not found
Example of error while attempting to bring up your Sitecore environment for the first time:
How to Fix Sitecore Docker “failed to solve: rpc error”
There are a lot of causes for this error. I'm going to go over some of the simpler ways to fix it, and hopefully it allows you to continue building great Sitecore websites.
Switch to Windows Containers
While working with Sitecore the biggest one is usually not using Windows Containers. Sitecore requires using Windows Containers to work correctly.
Enabling Windows Containers:
Open up the “Show Hidden Icons” section in the bottom right of your Windows Task Bar.
Right click on “Docker Desktop” and select “Switch to Windows Containers”.
You may get a prompt asking you if you are sure you want to switch to Windows containers because it will prevent you from managing any existing Linux containers until you switch back. This is fine and 100% expected. Just hit “Switch”.
Note: If your Docker gets stuck on “Starting the Docker Engine” scroll further down in this article to see the fix.
Enable Compose V2
Another requirement for running Sitecore in Docker is using “Docker Compose v2”. Depending on your version of docker, your settings screen will probably look different to mine - however, you should still be able to find a “Use Docker Compose v2” option under the “General” Tab.
Fixing Docker Stuck on “Starting the Docker Engine”
After you switch to Windows Containers, there is a chance your Docker has a meltdown and remains stuck on the following screen:
Let's go over some ways to fix this!
Attempt 1: Enabling Hyper-V
This is probably the most likely reason your Docker is stuck - Hyper-V is required to run Windows Containers. The only requirement to enable Hyper-V is to have a Pro or Enterprise version of windows, without it, you won't be able to get Windows Containers working on your machine.
Hyper-V Requirements: Windows 11 Pro or Enterprise
Once you are sure you have the correct version of windows, you just need to enable Hyper-V and try restarting Docker. To do so, open up a PowerShell window in Administrator mode, and run the following command:
Enable-WindowsOptionalFeature -Online -FeatureName $("Microsoft-Hyper-V", "Containers") -All
Attempt 2: Installing a New Linux Distro
You need to ensure that your linux containers are also working, to do that you need to run the wsl commands to ensure you have an up to date version of a linux distro.
Step 1: Uninstall Docker
Step 2: Reboot your Machine
Step 3: Install a Linux WSL Distro
To install a Linux distro, you can run the following command in a PowerShell window to see which distros are currently available: wsl --list --online.
From the provided list you just need to select a distro that you want and install it using the following command (Just replace {DISTRO-NAME} with the NAME of the distro): wsl --install -d {DISTRO-NAME}.
eg: wsl --install -d Ubuntu
If you get any WSL update errors, that's pretty common. You will just need to debug the individual error before you can continue your installation.
Step 4: Reinstall Docker Desktop
Attempt 3: Full Docker Uninstall
If you have attempted both options 1 & 2, and you still can't get your Sitecore environment up and running, then my last recommendation is to do a proper full docker uninstall and try again. You can also try reinstalling an older version of Docker when you go to install after the deep clean.
Step 1: Uninstall docker and delete files in the Docker Roaming folder
Press Windows + R and type “appdata”, Select Roaming → Docker.
Step 2: Reinstall Docker (Try using an older version)
Step 3: Unregister Docker
Open a PowerShell window in Administrator mode and type the two following commands.
wsl --unregister docker-desktop
wsl --unregister docker-desktop-data
Step 4: Stop the Docker Service
In the same Admin PowerShell window, you can run these two commands:
Net stop com.docker.service
Net start com.docker.service
Step 5: Restart Docker, and try again
Problem Solved!
Hopefully the suggestions made above should solve your Sitecore issues, however if they don't you can look at the following Stack Overflow thread for some more ideas on how to fix your Docker issues.
