Microsoft Connected Cache Linux Install Failure

Hello Stephen Fletcher,

Greetings! Thanks for raising this question in Q&A forum.

This is a well-known compatibility issue that started appearing after Docker Engine v29 was released. The root cause is that Docker Engine v29 bumped the minimum supported API version to 1.44, while the IoT Edge runtime (which Microsoft Connected Cache depends on) internally uses an older Docker client API version (1.34) that falls below this new minimum. This causes the MCC container to fail loading even though the deployment command itself completes successfully.

The good news is there is a clear workaround — replace Docker Engine with Microsoft's moby-engine, which is the officially supported container engine for IoT Edge and Connected Cache on Linux.

Here are the steps to fix this:

Step 1: Remove Docker Engine from your Ubuntu Server

sudo apt-get remove docker-ce docker-ce-cli containerd.io

Step 2: Add the Microsoft packages repository for Ubuntu 24.04

wget https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

Step 3: Install moby-engine (Microsoft's supported container engine)

Azure IoT Edge relies on an OCI-compatible container runtime. For production scenarios, use the Moby engine — it is the container engine officially supported with IoT Edge.

sudo apt-get update
sudo apt-get install moby-engine

Step 4: Reinstall Azure IoT Edge

sudo apt-get install aziot-edge

Step 5: Re-run the Microsoft Connected Cache deployment command

Once IoT Edge is back up with moby-engine, re-run your MCC deployment script from the Azure portal. The MCC container should now load successfully.

Step 6: Verify the installation

sudo iotedge system status
sudo iotedge list

You should see the MCC module listed and running.

A couple of important notes: Microsoft provides best-effort support for systems using Docker CE or Docker EE container engines; however, Microsoft cannot ship fixes for issues in them. For this reason, moby-engine is recommended for production systems. Also, Azure IoT Edge uses Moby-based Docker components (moby-engine, moby-cli) for container management, and these are updated to maintain compatibility with the Azure IoT Edge infrastructure.

This is currently a known open issue on the IoT Edge GitHub repository and a fix from the IoT Edge team is being tracked. In the meantime, using moby-engine is the recommended path forward.

If this answer helps you kindly accept the answer which will help others who have similar questions.

Best Regards,

Jerald Felix.