Docker Troubleshooting

This guide covers Docker-specific issues when running the WhoisXML API MCP Server. Docker provides excellent isolation and consistency, but can present unique challenges in certain environments.

Distroless Container

The WhoisXML API MCP Server Docker image is built using a distroless base image for security and minimal size. This means shell utilities like sh, bash, ping, etc. are not available inside the container. The troubleshooting methods in this guide account for this limitation and provide alternative debugging approaches.

Quick Resolution

Most Docker issues can be resolved by:

  1. Ensuring Docker is running: docker info
  2. Pulling the latest image: docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1
  3. Testing with a simple command: docker run --rm whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

Container Startup Issues

Container Won't Start or Exits Immediately

Symptoms:

  • Container exits with error code immediately
  • No output or minimal error messages
  • Docker command appears to hang

Diagnosis:

# Check if the image exists locally
docker images | grep mcp-whoisxmlapi

# Test image directly
docker run --rm whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# Check Docker daemon status
docker info

Solutions:

  1. Pull the latest image:

    docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1

  2. Test with minimal configuration:

    docker run --rm -e WHOISXMLAPI_TOKEN=test-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

  3. Check Docker daemon:

    # macOS/Windows: Start Docker Desktop
# Linux: Start Docker service
sudo systemctl start docker

Environment Variable Issues

Symptoms:

  • "API key token environment variable is required but was not set"
  • Server starts but authentication fails
  • Environment variables not being passed correctly

Diagnosis:

# Check if environment variables are passed correctly
# Start container in background to inspect
docker run -d --name mcp-test -e WHOISXMLAPI_TOKEN=test-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# Inspect container environment
docker inspect mcp-test | grep -A 20 "Env"

# Clean up test container
docker rm -f mcp-test

# For running containers
docker ps
docker inspect <container-id> | grep -A 20 "Env"

Solutions:

  1. Correct environment variable syntax:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env", "WHOISXMLAPI_TOKEN",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-actual-token-here"
      }
    }
  }
}

  2. Verify token format:

    # Token should start with "wxt-" or similar
echo $WHOISXMLAPI_TOKEN

  3. Test environment variable passing:

    # Start container briefly to test token
docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# If successful, token is being passed correctly
# For detailed inspection, use:
docker run -d --name token-test -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help && \
docker inspect token-test | grep -A 10 "Env" && \
docker rm -f token-test

Network and Port Issues

Port Already in Use (HTTP Server Mode)

Symptoms:

  • "Port 3000 already in use" or similar
  • Cannot bind to port errors
  • Connection refused when accessing HTTP endpoint

Diagnosis:

# Check what's using the port
lsof -i :3000
netstat -tlnp | grep :3000

# Try different port
docker run --rm -p 3001:3001 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --http --http-port 3001

Solutions:

  1. Use different port:

    docker run --rm -p 8080:8080 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --http --http-port 8080

  2. Stop conflicting service:

    # Find process using the port
lsof -i :3000
kill <process-id>

  3. Update client configuration:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-p", "8080:8080",
        "-e", "WHOISXMLAPI_TOKEN",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1",
        "--http", "--http-port", "8080"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token"
      }
    }
  }
}

Network Connectivity Issues

Symptoms:

  • "Connection refused" when server tries to reach WhoisXMLAPI
  • Timeouts on API requests
  • "Host not found" or DNS errors

Diagnosis:

# Test container network connectivity using Alpine
docker run --rm alpine ping -c 3 google.com
docker run --rm alpine nslookup whoisxmlapi.com

# Test MCP container connectivity by attempting a real API call
# (Note: distroless containers don't include network utilities)
docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# If that works, test network with a debug HTTP request
# (Check logs for network-related errors)

Solutions:

  1. Check host network connectivity:

    ping whoisxmlapi.com
curl -I https://www.whoisxmlapi.com

  2. Configure DNS (if needed):

    docker run --rm --dns 8.8.8.8 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

  3. Proxy configuration (corporate networks):

    docker run --rm \
  -e HTTP_PROXY=http://proxy.company.com:8080 \
  -e HTTPS_PROXY=http://proxy.company.com:8080 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

Volume and File System Issues

Debug Log File Problems

Symptoms:

  • Debug log file is created as a directory instead of a file
  • Permission denied when writing debug logs
  • Log file not accessible from host

Diagnosis:

# Check mount point
docker run --rm -v /tmp:/tmp alpine ls -la /tmp

# Check file permissions
ls -la /tmp/whoisxmlapi-debug.log

Solutions:

  1. Pre-create log file:

    touch /tmp/whoisxmlapi-debug.log
chmod 666 /tmp/whoisxmlapi-debug.log

  2. Use directory mount instead:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env", "WHOISXMLAPI_TOKEN",
        "--env", "WHOISXMLAPI_HTTP_DEBUG",
        "-v", "/tmp:/tmp",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token",
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/whoisxmlapi-debug.log"
      }
    }
  }
}

  3. Alternative log location:

    # Use /var/log if /tmp has issues
sudo mkdir -p /var/log/mcp
sudo chmod 777 /var/log/mcp

# Update configuration
"WHOISXMLAPI_HTTP_DEBUG": "/var/log/mcp/debug.log"

Permission Issues

Symptoms:

  • "Permission denied" when accessing mounted volumes
  • Cannot write to mounted directories
  • File ownership issues

Diagnosis:

# Check mount permissions
docker run --rm -v /tmp:/tmp alpine ls -la /tmp

# Check container user
docker run --rm whoisxmlapidotcom/mcp-whoisxmlapi:v1 id

Solutions:

  1. Fix directory permissions:

    chmod 755 /tmp
chmod 777 /tmp/mcp-logs  # For debug logs

  2. Run with specific user (if needed):

    docker run --rm --user $(id -u):$(id -g) \
  -v /tmp:/tmp \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

  3. Use Docker volume instead:

    # Create named volume
docker volume create mcp-logs

# Use in configuration
docker run --rm -v mcp-logs:/logs \
  -e WHOISXMLAPI_HTTP_DEBUG=/logs/debug.log \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

Performance and Resource Issues

Container Resource Limits

Symptoms:

  • Container killed by OOM (Out of Memory)
  • Slow performance
  • High CPU usage

Diagnosis:

# Monitor container resources
docker stats <container-id>

# Check system resources
docker system df
docker system info

Solutions:

  1. Set resource limits:

    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--memory=512m",
        "--cpus=1.0",
        "--env", "WHOISXMLAPI_TOKEN",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token"
      }
    }
  }
}

  2. Monitor resource usage:

    # Continuous monitoring
docker stats --no-stream <container-id>

# Check Docker system usage
docker system df

  3. Clean up resources:

    # Remove stopped containers
docker container prune

# Remove unused images
docker image prune

# Remove everything unused
docker system prune -a

Image Size and Storage Issues

Symptoms:

  • "No space left on device"
  • Slow image pulls
  • Storage warnings

Diagnosis:

# Check Docker storage usage
docker system df
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

# Check available disk space
df -h /var/lib/docker

Solutions:

  1. Clean up Docker storage:

    # Remove unused containers, networks, images
docker system prune -a

# Remove specific old images
docker rmi <old-image-id>

  2. Configure Docker storage:

    # Edit Docker daemon config (Linux)
sudo vi /etc/docker/daemon.json
{
  "data-root": "/path/to/larger/disk"
}

Platform-Specific Issues

macOS Issues

Docker Desktop not starting:

# Reset Docker Desktop
# Docker Desktop > Troubleshoot > Reset to factory defaults

# Check system requirements
system_profiler SPSoftwareDataType | grep "System Version"

Permission issues with volumes:

# Grant Docker access to directories in macOS System Preferences
# System Preferences > Security & Privacy > Files and Folders > Docker

Windows Issues

WSL 2 related problems:

# Check WSL 2 status
wsl --status
wsl --update

# Restart WSL if needed
wsl --shutdown

Hyper-V conflicts:

# Check Hyper-V status (requires admin)
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All

Linux Issues

Docker daemon not running:

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Check status
sudo systemctl status docker

User permissions:

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

# Test access
docker ps

Advanced Debugging

Container Inspection

# Get detailed container information
docker inspect <container-id>

# Check container logs
docker logs <container-id>
docker logs --tail 50 <container-id>

# Check environment and configuration
docker inspect <container-id> | jq '.[]|{Config,NetworkSettings,Mounts}'

# Monitor container activity
docker stats <container-id> --no-stream

Network Debugging

# Check Docker networks
docker network ls
docker network inspect bridge

# Test container networking
docker run --rm alpine ping -c 3 host.docker.internal
docker run --rm alpine nslookup whoisxmlapi.com

Image Debugging

# Inspect image layers
docker history whoisxmlapidotcom/mcp-whoisxmlapi:v1

# Test image functionality
docker run --rm whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help
docker run --rm whoisxmlapidotcom/mcp-whoisxmlapi:v1 --version

# Check image architecture and configuration
docker inspect whoisxmlapidotcom/mcp-whoisxmlapi:v1 | grep Architecture
docker inspect whoisxmlapidotcom/mcp-whoisxmlapi:v1 | jq '.[]|{Architecture,Os,Config}'

# For deeper debugging, use a debug Alpine container with same network
docker run --rm -it --network container:<mcp-container-id> alpine sh

Getting Help

Collecting Debug Information

When seeking help, collect this information:

# System information
docker version
docker info
uname -a

# Container information
docker ps -a
docker images | grep mcp-whoisxmlapi
docker logs <container-id>

# Configuration
cat your-mcp-config.json  # Remove tokens before sharing

Common Command Reference

# Basic troubleshooting commands
docker ps -a                          # List all containers
docker images                         # List images
docker logs <container-id>            # View logs
docker inspect <container-id>         # Detailed info
docker stats <container-id>           # Resource usage
docker system df                      # Storage usage
docker system prune                   # Cleanup

# Image management
docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1
docker rmi <image-id>                 # Remove image
docker history <image>                # Image history

# Network debugging
docker network ls                     # List networks
docker port <container-id>            # Port mappings

Prevention Tips

  1. Regular maintenance:

    # Weekly cleanup
docker system prune

# Update images
docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1

  2. Monitor resources:

    # Check before starting containers
docker system df
df -h /var/lib/docker

  3. Use health checks:

    # Test configuration before deployment
docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

  4. Keep logs manageable:

    # Configure log rotation in daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
Last Updated: