Technical Advisory: Docker Swarm

Key takeaways

• Docker Engine v29 introduces breaking API changes, causing older Docker clients, plugins, and tooling to fail outright, particularly for Docker Swarm environments.
• Legacy volume plugins can lose storage access in Swarm, making data appear unavailable even though it still exists on the storage system.
• Swarm users should upgrade cautiously and plan ahead, either maintaining Swarm carefully or preparing a gradual move to Kubernetes.

Since Docker Engine v29 was released, we have been tracking a number of breaking changes and regressions that disproportionately affect Docker Swarm users and anyone relying on legacy Docker plugins. This advisory summarizes the key issues and recommended mitigations.

Breaking Change: Minimum API Version Raised to v1.44

Docker v29 raised the minimum supported daemon API version to 1.44, dropping all compatibility with clients built against Docker Engine older than v25. Any tooling, plugin, or management platform compiled against an older API version receives a hard rejection. There is no fallback or negotiation. This single change broke a large portion of the Docker ecosystem.

Volume Plugin Failures: Storage Access Loss

Customers using legacy (V1) Docker volume plugins targeting enterprise storage systems (NFS, iSCSI, SAN/NAS) have been directly impacted. These plugins were compiled against older API versions and are now rejected by the v29 daemon. Due to Docker Swarm requiring cluster-scoped persistent storage, swarm users are disproportionally affected by this change.

The failure mode is severe: Docker retains volume metadata but cannot communicate with the plugin required to mount the volume, making data appear inaccessible, though it remains intact on the storage target.

We are aware of one very large enterprise customer that experienced a significant site-wide outage due to this very issue.

Recovering from Volume Plugin Failures

If you have been affected by this issue, Do not wipe /var/lib/docker. We recommend:

1. Downgrading Docker Engine to v26 or v27 to restore plugin communication
2. Exporting your data
3. Holding the package version (apt-mark hold docker-ce docker-ce-cli)
4. Planning migration to a V2 managed plugin (if one is available) or the native local volume driver.

Docker Swarm: Active Bugs

• **Mixed-Version Cluster Traffic Drops (v29.0.0–v29.2.0)**Upgrading some cluster nodes to v29 whilst others remain on older versions causes encrypted overlay traffic to silently stop. This precludes your ability to stage/stagger an upgrade. You must “all or nothing” your swarm hosts to v29.1.2 or later before if you are using encrypted overlay networks.
• Standalone Containers Cannot Communicate Cross-NodeA long-standing bug causes standalone containers on attachable overlay networks to hang when communicating across nodes. Deploy cross-node workloads as Swarm services as a workaround.

Docker Swarm: Key Structural Limitations

• nftables incompatibility: Swarm cannot run on hosts with nftables enabled, requiring legacy iptables shims on all modern Linux distributions.
• Overlay network ceiling: Networks become unstable above 1,000 containers due to kernel VXLAN limits.
• Overlay network VXLAN conflict: Overlay Networking leverages VXLAN, however VXLAN is now a very commonly used network technology, and many cloud service providers and Virtual Machine Infrastructure providers rely on VXLAN. When enabling Swarm overlay networks, you need to be mindful to change the default port that VXLAN uses to avoid conflicts.

Portainer's Position

Portainer fully supports Docker and Swarm.  Portainer has been fully compatible with Docker v29 since versions 2.33.5 LTS and 2.36.0 STS and users should ensure they are running these versions of Portainer or greater before upgrading your Docker Engine. However, given the combination of unresolved active bugs, growing ecosystem tool failures, and Swarm's structural limitations, we advise you to use caution with continuing to run Swarm, and with updating your systems to the latest Docker Engine versions.

Moving Forward

For those organizations currently running Docker Swarm, there are three practical options:

• Continue to run Swarm for your infrastructure, but taking care with lifecycle management
• Begin introducing Kubernetes as an orchestrator for new workloads
• Start planning a gradual migration away from Swarm on to Kubernetes

For customers considering a path forward, Portainer supports both Docker Swarm and Kubernetes from a single management plane. This supports you and your team whether you decide to stay with Swarm or begin the move to Kubernetes, all from within the same interface.

For more on running (and migrating from) Docker Swarm in 2026, we have prepared a whitepaper that takes a deeper dive into the risks of Docker Swarm, the inherent limitations of continuing to use Swarm, and what your options are for the future.

{{article-cta}}

We are also happy to discuss and assist with migration options that minimize disruption to your existing workloads. Reach out to our support team for more information.

One platform, not twelve tools.

Govern Kubernetes across your whole fleet from a single control plane. Get 3 nodes free.

Get 3 nodes freeTalk to technical sales

Get 3 nodes free More from the blog