Docker Compose Connection Refused Error: API Version Fetch Issue

When running docker-compose up, you might encounter the connection error:

docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', ConnectionRefusedError(61, 'Connection refused'))

This error indicates that Docker Compose cannot communicate with the Docker daemon. Below are the most effective solutions organized by environment.

Verify Docker Service Status

First, ensure the Docker service is actually running:

systemctl status docker.service

If Docker isn't running, start it with one of these commands:

# Systemd-based systems (most modern Linux distributions)
sudo systemctl start docker
sudo systemctl enable docker  # Enable auto-start on boot

# SysV init systems
sudo service docker start

# Alternative init script
sudo /etc/init.d/docker restart

Permission Solutions

Add User to Docker Group

The most common solution is to add your user to the Docker group:

# Create docker group if it doesn't exist
sudo groupadd docker

# Add your user to the docker group
sudo usermod -aG docker $USER

# Apply group changes (requires logout/login or use newgrp)
newgrp docker

After running these commands, log out and log back in or restart your terminal session for the changes to take effect.

Adjust Socket Permissions (Temporary Fix)

For immediate access, you can modify the Docker socket permissions:

sudo chmod o+rw /var/run/docker.sock
# OR more permissive
sudo chmod 666 /var/run/docker.sock

WARNING

This method grants broad permissions and may have security implications. Prefer the user group method for long-term solutions.

Platform-Specific Solutions

Docker Desktop Users

If you're using Docker Desktop:

1. Ensure Docker Desktop is actually running
2. Check that it's set to launch at login (in settings)
3. Restart Docker Desktop if recently updated

WSL (Windows Subsystem for Linux) Users

For WSL environments:

1. Ensure WSL integration is enabled in Docker Desktop settings
2. Restart Docker Desktop after enabling WSL support
3. Verify your distribution is selected in Docker Desktop's WSL settings

macOS Solutions

On macOS, try these steps:

1. Check "Open at Login" in Docker Desktop settings
2. Restart your system if Docker Desktop won't start
3. Consider downgrading if the issue started after an update

Advanced Troubleshooting

Check Docker Context

Docker might be using an incorrect context:

# List available contexts
docker context list

# Switch to default context
docker context use default

Environment Refresh

Sometimes shell environment needs refreshing:

source ~/.bashrc  # Or appropriate shell config file

Production Environment Considerations

For Linux servers and production environments (like AWS EC2 instances):

# Ensure docker service is enabled and started
sudo systemctl enable docker.service
sudo systemctl start docker.service

# Add user to docker group
sudo usermod -aG docker <your-username>

# Ensure docker-compose has execute permissions
sudo chmod +x /usr/local/bin/docker-compose

Verification

After applying any solution, verify Docker is working correctly:

# Check Docker version
docker --version

# Verify Docker daemon communication
docker ps

# Test docker-compose
docker-compose --version

Conclusion

The "Connection refused" error when running docker-compose up typically stems from one of these issues:

1. Docker service not running
2. User lacking permissions to access Docker daemon
3. Docker Desktop not properly launched
4. Environment configuration issues

Start with checking the Docker service status and adding your user to the Docker group, as these resolve the majority of cases. For platform-specific issues, refer to the appropriate section above.

TIP

Always prefer the user group method (usermod -aG docker $USER) over broad permission changes for security reasons.