During a recent training session I was leading, I watched a room full of sharp engineers do what engineers do best: follow instructions precisely. We installed Portainer together, step by step, expecting the usual smooth glide into the world of container management. Instead, we hit a wall. A small one. The kind that wastes twenty minutes and drains confidence.
The error message appeared:
The Podman environment option doesn't support Docker environments.
Please select the Docker option instead.
That was odd. We were very much using Docker, not Podman. Yet Portainer insisted otherwise.
The culprit turned out not to be Docker itself, nor Portainer being "broken," but an API version mismatch. Portainer expects Docker to expose at least API version 1.24. Newer Docker versions still support it, but they do not advertise it unless asked politely.
The fix is almost disappointingly simple, and crucially, it does not require downgrading anything. You tell Docker to expose the minimum API version explicitly.
Edit the Docker systemd service:
systemctl edit docker.service
Add this above the line that warns you it will discard changes:
[Service]
Environment=DOCKER_MIN_API_VERSION=1.24
Save, exit, then restart Docker:
systemctl restart docker
Portainer immediately stops pretending your Docker engine is Podman.
In our case, this was tested on Portainer 2.27.3 LTS Community Edition, and everything worked cleanly afterward. Training resumed. Coffee regained its warmth.
One caveat, because reality always sneaks in. If you are using the Business Edition, you may hit a known issue where docker-compose.yml files do not appear correctly for stacks. The Community Edition does not suffer from this particular annoyance.
Infrastructure fails over the smallest details, a single missing environment variable, a version number assumed but not declared. Systems are honest, but they are not kind.
If you want the original thread where this rabbit hole began, it lives here on GitHub in the Portainer issue tracker.
Also, you might find some of my training materials useful. They are available on FAUN.sensei(). You'll find courses on Docker, Kubernetes, Rancher, DevSecOps, Ansible, and more. Check them out!
