When working with containerized environments, version compatibility between Docker clients and servers can become a pain point. Here's what happens when you try to connect a newer Docker client (v1.4.1) to an older Docker host (v1.3.2):

$ docker version
Client version: 1.4.1
Client API version: 1.16
Go version (client): go1.4
Git commit (client): 5bc2ff8
OS/Arch (client): darwin/amd64
FATA[0000] Error response from daemon: client and server don't have same version (client : 1.16, server: 1.15)

Interestingly, tools like Fig (now Docker Compose) can still function because they often implement their own API version negotiation. Here's proof it works:

$ cat > fig.yml
test:
    image: busybox
$ fig run --rm test sh
/ # hostname -f
084f75fb59d4

The solution is to explicitly set the API version when initializing your Docker client connection. There are several ways to achieve this:

Method 1: Environment Variable

The most straightforward approach is using the DOCKER_API_VERSION environment variable:

export DOCKER_API_VERSION=1.15
docker version  # Now this should work
docker ps       # And other commands

Method 2: Client Configuration File

For persistent configuration, create or modify ~/.docker/config.json:

{
  "auths": {
    "https://index.docker.io/v1/": {}
  },
  "HttpHeaders": {
    "User-Agent": "Docker-Client/1.15"
  },
  "apiVersion": "1.15"
}

Method 3: Docker Client Wrapper Script

Create a wrapper script to enforce the version:

#!/bin/bash
export DOCKER_API_VERSION=1.15
/usr/local/bin/docker "$@"

While forcing an older API version works, be aware of these limitations:

• Newer features won't be available (e.g., health checks, secrets)
• Some commands might behave differently
• Security patches in newer versions are missing

If you frequently work with legacy Docker hosts, consider these approaches:

# SSH tunneling for direct access
ssh -L /var/run/docker.sock:/var/run/docker.sock user@legacy-host

# Docker Machine with API version flag
docker-machine create --driver generic \
  --generic-ssh-user user \
  --generic-ip-address legacy-host \
  --engine-api-version 1.15 \
  legacy-host

Remember that these are temporary solutions until you can upgrade your Docker hosts. The API version mismatch will only grow as time passes and newer Docker client versions are released.

---

When connecting a modern Docker client (v1.4.1) to an older Docker daemon (v1.3.2), you'll encounter API version incompatibility errors:

$ docker version
Client version: 1.4.1
Client API version: 1.16
...
FATA[0000] Error response from daemon: client and server don't have same version (client : 1.16, server: 1.15)

Tools like Fig (now Docker Compose) often implement their own API version negotiation logic. Examining the connection pattern reveals:

$ FIG_DEBUG=1 fig run --rm test sh
[debug] Using API version: 1.15
[debug] Connecting to: tcp://dockerhost:2376

Set the DOCKER_API_VERSION environment variable to match your server's API version:

# For Linux/macOS shell:
export DOCKER_API_VERSION=1.15

# For Windows PowerShell:
$env:DOCKER_API_VERSION="1.15"

Verify the setting took effect:

$ docker version
Client version: 1.4.1
Client API version: 1.15  # Notice the downgrade
Server version: 1.3.2
Server API version: 1.15

For persistent configuration across sessions:

# Add to ~/.bashrc or ~/.zshrc
echo 'export DOCKER_API_VERSION=1.15' >> ~/.bashrc

# Alternatively, in your Docker config file
echo '{"apiVersion":"1.15"}' > ~/.docker/config.json

Be aware of missing functionality in older API versions:

• No docker exec support (added in API v1.18)
• Limited healthcheck capabilities
• Simpler volume management

When using Docker over TLS with older versions:

# Explicitly specify TLS parameters
docker --tlsverify \
  --tlscacert=ca.pem \
  --tlscert=cert.pem \
  --tlskey=key.pem \
  -H=tcp://dockerhost:2376 \
  version

For consistent behavior, install matching client version:

# On macOS with Homebrew
brew uninstall docker
brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/9b37161f61bcf9c0f6d7e3d7b70e4e7b827a7c6a/Formula/docker.rb

# Verify installation
docker version | grep 1.3.2

For cases requiring newer API features, consider these workarounds:

# Use docker-py to implement missing functionality
import docker
client = docker.Client(base_url='tcp://dockerhost:2376', version='1.15')

# Implement healthchecks via external scripts
docker run -d --name legacy-healthcheck \
  -v /usr/local/bin/healthcheck.sh:/healthcheck.sh \
  myapp /healthcheck.sh