What Happened

#

Earlier this week folks began noticing that various applications were breaking, such as CasaOS, Portainer, and even Traefik, among others.

What did they all have in common? They all interacted with Docker. Specifically, they all used the Docker API to communicate with Docker.

Why This Happened

#

Turns out that Docker released Docker Engine v29.0 earlier this week. This version came with API v1.52. This update was pushed out by various package managers including to my own Ubuntu 24.04.x LTS VMs. This in itself was not the issue, however.

What was NOT clearly telegraphed well ahead of time or articulated by the Docker team was that this version by default stopped support API versions < 1.44.

Currently many apps such as the ones listed are still using older versions of the Docker API. CasaOS, for example, is still using API v1.24.

Worse, Docker’s own release notes on this version failed to show v29.0.0 had even been released until sometime in the past few days. Their API version history also failed to show v1.52 until recently as well.

Now, as I type this, I see that they finally updated the former and indicate the version was released on 2025-11-10. However, such a breaking change should have been announced long before release.

So this week saw many folks suddenly finding these applications breaking, not understanding why, and scrambling to find a fix (myself included).

Once the root cause was determined, the various fixes started rolling in, from reverting to an older version of Docker Engine such as v28.5.2 to reinstalls of apps, etc.

The Real Issue

#

The key issue is what version of the Docker API a client application uses vs. which versions of that API the Docker Engine supports. In most REST API environments which follow semantic versioning, any update to an existing major version (e.g., v1) should still support calls to any older version.

However, for whatever reason, Docker has chosen to cut off support to older subversions below API v1.44 by default with the release of Docker Engine v29.0. THIS is what caused these applications to break.

Some will argue that client developers should update their API versions. And while that is typically a good idea in order to fix bugs, security issues, etc., I still fault Docker for its failure to properly announce this WELL in advance.

That said, Docker did provide ways to override the minimum API version that is supported, as noted here.

Initially I followed the instructions here (with one adjustment, as I had to also sudo systemctl stop docker.socket) to revert my version of Docker Engine to v28.5.2. That worked just fine. But knowing what I know now, I prefer the following instead.

Easier Fix: Tell Docker v29.x+ to support older API versions

#

Many folks do not wish to downgrade their version of Docker from the latest current v29.x. And there are many good reasons for this, including security patches, etc.

The alternative is simply to override Docker’s default configuration to tell it to support older API versions.

In my case, this was API v1.24. YMMV.

You can do this in at least two different ways.

FIX OPTION 1: Edit /etc/docker/daemon.json (preferred method)

#

The easiest and cleanest method is to edit the daemon.json file and restart Docker. For example, on my Ubuntu 24.04 LTS VM, there was no such file. So I simply followed these steps. (Adjust according to your OS/distro.)

1. Open /etc/docker/daemon.json in an editor

#

sudo nano /etc/docker/daemon.json

2. Copy/Paste the following into the file

#

If the file is empty, simply paste the following into the file:

#

{
  "min-api-version": "1.24"
}

If the file is NOT empty ¹, paste the following just below the opening brace “{”:

#

  "min-api-version": "1.24",

3. Save the file

#

Hit [CTRL][X] to exit, [Y] to save.

4. Restart docker

#

sudo systemctl restart docker.service

Or simply reboot.

- OR -

#

FIX OPTION 2: Modify Docker service to add Environment Variable

#

Thanks to various posts such as this one.

1. Edit Docker service

#

sudo systemctl edit docker.service

The top of the file reads

### Editing /etc/systemd/system/docker.service.d/override.conf
### Anything between here and the comment below will become the contents of the drop-in file



### Edits below this comment will be discarded
...

2. Copy/paste the following lines in the open space between the comment lines shown above:

#

[Service]
Environment=DOCKER_MIN_API_VERSION=1.24

3. Save the file

#

Hit [CTRL][X] to exit, [Y] to save.

4. Restart Docker

#

sudo systemctl restart docker.service

Or simply reboot.

Context

#

If you read this you will see that

Docker versions older than v25 are now end of life, and as such, we have increased the Minimum API version to 1.44 (Moby v25).

They then provide ways to override the minimum API version supported. So clearly they are aware that some folks may run into issue.

I personally prefer the daemon.json approach, as on my system that file did not exist previously. Assuming no more changes to this file, once the impacted app updates to a newer API version (v1.44+), all I need to do is delete the daemon.json file and restart Docker to have it running in the default Docker configuration again. YMMV.