The official Docker getting-started tutorial uses Traefik v3.4 as a reverse proxy, but that version has a Docker API compatibility issue that prevents the application from running.
Traefik continuously errors with "client version 1.24 is too old. Minimum supported API version is 1.44" despite the Docker daemon supporting API version 1.52.
This makes the tutorial non-functional for users, contradicting the tutorial's promise that "you only need Docker Desktop. The rest just works."
Environment
• Repository: [https://github.com/docker/getting-started-todo-app]
• Docker Version: 29.1.5
• Docker API Version: 1.52 (minimum version 1.44)
• OS: Ubuntu 24.04 LTS (also affects other Linux distributions)
• Traefik Version: v3.4 (as specified in compose.yaml)
• Docker Compose: Included with Docker 29.1.5
Steps to Reproduce
- Clone the repository:
- git clone [https://github.com/docker/getting-started-todo-app]
- cd getting-started-todo-app
- Start the development environment:
- docker compose watch
- Observe the proxy container logs:
- docker compose logs proxy
- Navigate to http://localhost:3000/ (or http://localhost/ if using default port 80)
- Observe "404 page not found" error
Expected Result
• All containers start successfully
• Traefik proxy routes requests correctly to frontend and backend services
• Application is accessible at http://localhost/
• No errors in container logs
• Tutorial works as documented: "you only need Docker Desktop. The rest just works"
Actual Result
• Containers start but Traefik proxy fails to configure routing
• Continuous error loop in proxy logs:
• proxy-1 | time="2026-02-10T15:58:37Z" level=error msg="Failed to retrieve information of the docker client and server host: Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" providerName=dockerproxy-1 | time="2026-02-10T15:58:37Z" level=error msg="Provider connection error Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version, retrying in 1.107050362s" providerName=docker
• Application returns "404 page not found"
• No routes are configured in Traefik
• Tutorial is completely broken
Visual Proof
Browser showing 404 error:
• User navigates to http://localhost:3000/
• Browser displays "404 page not found"
Docker container status:
$ docker compose ps
NAME IMAGE STATUS
getting-started-todo-app-backend-1 getting-started-todo-app-backend Up 2 minutes
getting-started-todo-app-client-1 getting-started-todo-app-client Up 2 minutes
getting-started-todo-app-mysql-1 mysql:9.3 Up 2 minutes (healthy)
getting-started-todo-app-phpmyadmin-1 phpmyadmin Up 2 minutes
getting-started-todo-app-proxy-1 traefik:v3.4 Up 2 minutes
Proxy logs showing continuous errors:
$ docker compose logs proxy | head -20
proxy-1 | 2026-02-10T15:49:06Z ERR Failed to retrieve information of the docker client and server host error="Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" providerName=docker
proxy-1 | 2026-02-10T15:49:06Z ERR Provider error, retrying in 14.748772293s error="Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" providerName=docker
[errors repeat continuously]
Logs
Full error output from Traefik container:
time="2026-02-10T15:42:42Z" level=error msg="Failed to retrieve information of the docker client and server host: Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" providerName=docker
time="2026-02-10T15:42:42Z" level=error msg="Provider connection error Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version, retrying in 7.527462627s" providerName=docker
This error repeats indefinitely in a retry loop.
Severity
High - Tutorial is completely broken and non-functional
Impact:
• New users following the official Docker tutorial cannot complete it
• Damages trust in Docker's documentation quality
• Wastes developer time troubleshooting what should be a working example
• Affects all users on modern Docker installations (Docker 20.10+)
Root Cause Analysis
Traefik v3.4 (and v3.0-v3.3) has a bug where it negotiates down to Docker API version 1.24 when connecting to the Docker socket, despite the Docker daemon supporting API 1.52. Docker daemon's minimum supported API version is 1.44, causing a version mismatch.
Traefik v2.x versions (tested v2.9, v2.10) exhibit the same issue.
Tested Workarounds
❌ Failed Attempts:
- Traefik v3.0-v3.4: All fail with same API version error
- Traefik v2.9-v2.10: All fail with same API version error
- Setting DOCKER_API_VERSION environment variable: No effect
- Different port configurations: Unrelated to API version issue
✅ Working Solution:
Replace Traefik with nginx reverse proxy. This requires users to:
- Create custom nginx.conf file
- Modify compose.yaml to use nginx instead of Traefik
This defeats the purpose of a "getting started" tutorial.
Proposed Solutions
Solution 1: Use Compatible Traefik Version (Recommended)
Test and identify a Traefik version that works with modern Docker API, or use an alternative simple proxy.
Pros:
• Minimal changes to tutorial
• Maintains tutorial simplicity
• Quick fix
Cons:
• May require finding alternative to Traefik entirely
Solution 2: Update compose.yaml with API Version Fix
If a Traefik version can be configured to work, update the compose.yaml with appropriate settings.
Solution 3: Replace with Simpler Proxy
Use nginx or Caddy which don't have this Docker API version issue.
Pros:
• Guaranteed to work
• More widely used in production
Cons:
• Requires additional configuration file
• More complex for beginners
Solution 4: Document Prerequisites and Troubleshooting
Add clear documentation about:
• Docker version requirements
• Common port conflicts (port 80, 8000, 8080 often in use)
• Troubleshooting steps for Traefik failures
Additional Context
• First noticed: Testing the tutorial on February 10, 2026
• Frequency: 100% reproducible on all tested Docker versions 20.10+
• Workaround: Switch to nginx (requires creating nginx.conf and modifying compose.yaml)
• Related issues: This appears to be a known Traefik issue with Docker API negotiation
• User base affected: All new users following this getting-started tutorial
Additional Port Conflict Issue
The tutorial assumes port 80 is available, but many users have services on port 80 (or port 8000 mentioned in some configurations). The tutorial should either:
• Document how to change ports
• Use a less commonly occupied port by default (e.g., 3000)
• Add troubleshooting for "port already allocated" errors
Files Affected
• compose.yaml - Lines 44-50 (proxy service configuration)
• Documentation at [https://docs.docker.com/get-started/workshop/develop-with-containers/]
Suggested Documentation Updates
- Add troubleshooting section for common failures
- Document system requirements more clearly
- Add guidance on changing default ports
- Test tutorial on fresh installations regularly
- Consider automated CI testing of tutorial repositories
Related Links
• Tutorial: [https://docs.docker.com/get-started/workshop/develop-with-containers/]
• Repository: [https://github.com/docker/getting-started-todo-app]
• Traefik Docker Provider Docs: [https://doc.traefik.io/traefik/providers/docker/]
The official Docker getting-started tutorial uses Traefik v3.4 as a reverse proxy, but that version has a Docker API compatibility issue that prevents the application from running.
Traefik continuously errors with "client version 1.24 is too old. Minimum supported API version is 1.44" despite the Docker daemon supporting API version 1.52.
This makes the tutorial non-functional for users, contradicting the tutorial's promise that "you only need Docker Desktop. The rest just works."
Environment
• Repository: [https://github.com/docker/getting-started-todo-app]
• Docker Version: 29.1.5
• Docker API Version: 1.52 (minimum version 1.44)
• OS: Ubuntu 24.04 LTS (also affects other Linux distributions)
• Traefik Version: v3.4 (as specified in compose.yaml)
• Docker Compose: Included with Docker 29.1.5
Steps to Reproduce
Expected Result
• All containers start successfully
• Traefik proxy routes requests correctly to frontend and backend services
• Application is accessible at http://localhost/
• No errors in container logs
• Tutorial works as documented: "you only need Docker Desktop. The rest just works"
Actual Result
• Containers start but Traefik proxy fails to configure routing
• Continuous error loop in proxy logs:
• proxy-1 | time="2026-02-10T15:58:37Z" level=error msg="Failed to retrieve information of the docker client and server host: Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" providerName=dockerproxy-1 | time="2026-02-10T15:58:37Z" level=error msg="Provider connection error Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version, retrying in 1.107050362s" providerName=docker
• Application returns "404 page not found"
• No routes are configured in Traefik
• Tutorial is completely broken
Visual Proof
Browser showing 404 error:
• User navigates to http://localhost:3000/
• Browser displays "404 page not found"
Docker container status:
$ docker compose ps
NAME IMAGE STATUS
getting-started-todo-app-backend-1 getting-started-todo-app-backend Up 2 minutes
getting-started-todo-app-client-1 getting-started-todo-app-client Up 2 minutes
getting-started-todo-app-mysql-1 mysql:9.3 Up 2 minutes (healthy)
getting-started-todo-app-phpmyadmin-1 phpmyadmin Up 2 minutes
getting-started-todo-app-proxy-1 traefik:v3.4 Up 2 minutes
Proxy logs showing continuous errors:
$ docker compose logs proxy | head -20
proxy-1 | 2026-02-10T15:49:06Z ERR Failed to retrieve information of the docker client and server host error="Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" providerName=docker
proxy-1 | 2026-02-10T15:49:06Z ERR Provider error, retrying in 14.748772293s error="Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" providerName=docker
[errors repeat continuously]
Logs
Full error output from Traefik container:
time="2026-02-10T15:42:42Z" level=error msg="Failed to retrieve information of the docker client and server host: Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version" providerName=docker
time="2026-02-10T15:42:42Z" level=error msg="Provider connection error Error response from daemon: client version 1.24 is too old. Minimum supported API version is 1.44, please upgrade your client to a newer version, retrying in 7.527462627s" providerName=docker
This error repeats indefinitely in a retry loop.
Severity
High - Tutorial is completely broken and non-functional
Impact:
• New users following the official Docker tutorial cannot complete it
• Damages trust in Docker's documentation quality
• Wastes developer time troubleshooting what should be a working example
• Affects all users on modern Docker installations (Docker 20.10+)
Root Cause Analysis
Traefik v3.4 (and v3.0-v3.3) has a bug where it negotiates down to Docker API version 1.24 when connecting to the Docker socket, despite the Docker daemon supporting API 1.52. Docker daemon's minimum supported API version is 1.44, causing a version mismatch.
Traefik v2.x versions (tested v2.9, v2.10) exhibit the same issue.
Tested Workarounds
❌ Failed Attempts:
✅ Working Solution:
Replace Traefik with nginx reverse proxy. This requires users to:
This defeats the purpose of a "getting started" tutorial.
Proposed Solutions
Solution 1: Use Compatible Traefik Version (Recommended)
Test and identify a Traefik version that works with modern Docker API, or use an alternative simple proxy.
Pros:
• Minimal changes to tutorial
• Maintains tutorial simplicity
• Quick fix
Cons:
• May require finding alternative to Traefik entirely
Solution 2: Update compose.yaml with API Version Fix
If a Traefik version can be configured to work, update the compose.yaml with appropriate settings.
Solution 3: Replace with Simpler Proxy
Use nginx or Caddy which don't have this Docker API version issue.
Pros:
• Guaranteed to work
• More widely used in production
Cons:
• Requires additional configuration file
• More complex for beginners
Solution 4: Document Prerequisites and Troubleshooting
Add clear documentation about:
• Docker version requirements
• Common port conflicts (port 80, 8000, 8080 often in use)
• Troubleshooting steps for Traefik failures
Additional Context
• First noticed: Testing the tutorial on February 10, 2026
• Frequency: 100% reproducible on all tested Docker versions 20.10+
• Workaround: Switch to nginx (requires creating nginx.conf and modifying compose.yaml)
• Related issues: This appears to be a known Traefik issue with Docker API negotiation
• User base affected: All new users following this getting-started tutorial
Additional Port Conflict Issue
The tutorial assumes port 80 is available, but many users have services on port 80 (or port 8000 mentioned in some configurations). The tutorial should either:
• Document how to change ports
• Use a less commonly occupied port by default (e.g., 3000)
• Add troubleshooting for "port already allocated" errors
Files Affected
• compose.yaml - Lines 44-50 (proxy service configuration)
• Documentation at [https://docs.docker.com/get-started/workshop/develop-with-containers/]
Suggested Documentation Updates
Related Links
• Tutorial: [https://docs.docker.com/get-started/workshop/develop-with-containers/]
• Repository: [https://github.com/docker/getting-started-todo-app]
• Traefik Docker Provider Docs: [https://doc.traefik.io/traefik/providers/docker/]