Monday, November 15, 2021

Troubleshooting BcContainerHelper Docker Build Errors on Windows 10 versions 21H1 and 21H2

by Steve Endow

If you've been using Docker Desktop on Windows 10 to build Business Central Docker containers with BcContainerHelper, you have likely encountered build errors for some reason.

Freddy Kristiansen has been constantly working to improve BcContainerHelper to deal with weird Windows version issues and Docker Desktop quirks, but it seems that Windows 10 versions 21H1 and 21H2 are currently causing some build errors, despite Freddy's best efforts.

If you are unsure which Windows 10 "version" you have, you can click on the Windows Start button and type "winver".  

Windows 10 - Version 21H2

I've reviewed a few issues on the BcContainer GitHub repository while helping a few people troubleshoot BC container build issues recently, and it appears there are currently 3 techniques to try and resolve errors when using Docker Desktop and BcContainerHelper on Windows 10 versions 21H1 and 21H2.

As of November 2021, if you are using Windows 10 version 21H1 or 21H2, you should see this warning from BcContainerHelper during the build process.

Windows 10 21H1 / 21H2 Warning Message

If you do see this message during your build, do not be surprised if the Docker Container build process fails.

Here's an example of one type of error that may occur:  "Docker Build failed with exit code -1"

Docker Build failed with exit code -1

Here are the 4 workarounds that seem to help resolve errors on the newer versions of Windows 10.


1. Temporarily disable Windows Defender Real-time Protection (under "Windows Security").  It seems that Windows Defender real-time virus scanning is interfering with the Docker Container build process, and either causing some type of file lock, or a quarantine, that is interfering with the build process.  Disabling the Real-time protection stops the file scanning, which may resolve your build error.

After the container is successfully created, you can re-enable the Real-time protection.  (but you'll probably need to turn it back off again temporarily the next time you create a new container)

Windows Defender Real-time protection setting


2. Completely disable Windows Defender temporarily (under "Windows Security").  A developer shared with me that he had previously been able to disable Defender Real-time Protection to build BC Docker Containers, but recently, that stopped working.  When he completely disabled 


3. Remove the imageName parameter from the BcContainerHelper script.  I saw this mentioned in a GitHub Issue, and it seems to have worked for Matthew Perren.

I don't know if the image creation process is triggering an error directly, or if skipping the named image process avoids a potential issue with Defender that is causing the problem.  But if disabling Defender Real-time protection alone doesn't work, try removing imageName.


4. Try adding the "-isolation hyperv" parameter to the BcContainerHelper script.  This used to be the go-to solution for a version mismatch between the host OS and the container OS, but it seems that with 21H1 and 21H2 the isolation mode does not always resolve build errors.


If you do encounter container build issues with Windows 10 version 21H1 or 21H2, please let me know if one of the steps above worked for you, or if you found a different solution to your build error.


Steve Endow is a Microsoft MVP in Los Angeles.  He works with Dynamics 365 Business Central.

You can also find him on Twitter and YouTube

No comments:

Post a Comment

All comments must be reviewed and approved before being published. Your comment will not appear immediately.

Business Central API - Filter Child Array Values Using $filter Query Option

 by Steve Endow I had a difficult time finding an example of this type of API filtering using the OData $filter query option, so I wanted to...