Skip to content

StackWiz MCP Troubleshooting Guide

This guide helps you diagnose and resolve common issues when using StackWiz MCP.

Quick Diagnostics

Check StackWiz MCP Status

Ask Claude:

"Check if StackWiz MCP is working properly"

Or run manually: 

# Check if server is running
ps aux | grep stackwiz_mcp

# Test server health
curl http://localhost:8765/health

# View server logs
tail -f ~/.cache/stackwiz-mcp/logs/server.log

Common Issues

1. StackWiz MCP Not Available in Claude

Symptoms: - Claude says "I don't have access to StackWiz MCP" - Tools not showing up in Claude's interface

Solutions:

  1. Check Claude Desktop Configuration: 

    # macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
cat ~/.config/claude/claude_desktop_config.json

  2. Verify Configuration Format: 

    {
  "mcpServers": {
    "stackwiz": {
      "command": "python",
      "args": ["-m", "stackwiz_mcp"],
      "env": {
        "STACKWIZ_BASE_DIR": "/srv/dockerdata"
      }
    }
  }
}

  3. Restart Claude Desktop:

  4. Completely quit Claude Desktop
  5. Start it again

  6. Check if StackWiz appears

  7. Test Manual Start: 

    python -m stackwiz_mcp
# Should see: "INFO: Started server process"

2. Stack Creation Fails

Symptoms: - Error: "Failed to create stack" - Docker compose errors

Solutions:

  1. Check Docker Access: 

    # Test Docker access
docker ps

# If permission denied:
sudo usermod -aG docker $USER
# Log out and back in

  2. Verify Base Directory: 

    # Check permissions
ls -la /srv/dockerdata

# Fix permissions if needed
sudo chown -R $USER:docker /srv/dockerdata
sudo chmod 755 /srv/dockerdata

  3. Check Port Conflicts: 

    # See what's using a port
sudo lsof -i :80
sudo lsof -i :443

# Or check Docker ports
docker ps --format "table {{.Names}}\t{{.Ports}}"

  4. Validate Image Name: 

    # Test pulling image
docker pull nginx:latest

3. DNS Creation Fails

Symptoms: - Error: "Failed to create DNS record" - Cloudflare API errors

Solutions:

  1. Check Cloudflare Credentials: 

    # Verify environment variables
echo $CF_API_EMAIL
echo $CF_DNS_API_TOKEN

  2. Test Cloudflare API: 

    # Test API access
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer $CF_DNS_API_TOKEN" \
  -H "Content-Type: application/json"

  3. Verify Domain Zone:

  4. Ensure domain is in your Cloudflare account

  5. Check API token has correct permissions:

    • Zone:DNS:Edit
    • Zone:Zone:Read

  6. Manual DNS Creation: 

    # Use the manual script
/srv/dockerdata/_scripts/cloudflare-dns-create.sh subdomain

4. Service Not Accessible

Symptoms: - Service running but can't access via URL - SSL certificate errors

Solutions:

  1. Check Traefik: 

    # Verify Traefik is running
docker ps | grep traefik

# Check Traefik logs
docker logs traefik

# Verify routing rules
docker exec traefik cat /etc/traefik/dynamic/

  2. Verify Labels: 

    # Check service labels
docker inspect <container_name> | grep -A 20 Labels

  3. DNS Propagation: 

    # Check DNS resolution
nslookup subdomain.rbnk.uk
dig subdomain.rbnk.uk

# Check from different nameserver
dig @8.8.8.8 subdomain.rbnk.uk

  4. Port Forwarding (if using Proxmox):

  5. Ensure port 443 is forwarded from Proxmox host to VM
  6. Check iptables rules on Proxmox host

5. Container Keeps Restarting

Symptoms: - Service status shows "Restarting" - Container exits immediately

Solutions:

  1. Check Logs: 

    # View container logs
docker logs <container_name>

# Follow logs
docker logs -f <container_name>

  2. Common Causes:

  3. Missing environment variables
  4. Incorrect file permissions
  5. Port already in use

  6. Invalid configuration

  7. Debug Mode: 

    # Run interactively
docker run -it --rm \
  --network traefik_proxy \
  -e ENV_VAR=value \
  image_name:tag \
  /bin/sh

6. Permission Errors

Symptoms: - "Permission denied" errors - Can't write to volumes

Solutions:

  1. Fix Volume Permissions: 

    # Check current permissions
ls -la /srv/dockerdata/stack-name/

# Fix ownership
sudo chown -R $USER:docker /srv/dockerdata/stack-name/

# Fix permissions
sudo chmod -R 755 /srv/dockerdata/stack-name/
sudo chmod 640 /srv/dockerdata/stack-name/.env

  2. User/Group Issues: 

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

# Verify groups
groups

7. Resource Limits Hit

Symptoms: - Out of memory errors - Disk space issues - CPU throttling

Solutions:

  1. Check Resources: 

    # Disk space
df -h /srv/dockerdata

# Memory usage
free -h

# Docker resource usage
docker stats --no-stream

  2. Clean Up: 

    # Remove unused images
docker image prune -a

# Remove unused volumes
docker volume prune

# Remove stopped containers
docker container prune

  3. Adjust Limits: Ask Claude:

    "Update the Redis service to use only 256MB of memory"

Advanced Troubleshooting

Enable Debug Logging

  1. Set Debug Mode: 

    export STACKWIZ_LOG_LEVEL=DEBUG

  2. In Claude Configuration: 

    {
  "mcpServers": {
    "stackwiz": {
      "env": {
        "STACKWIZ_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Direct API Testing

Test StackWiz MCP directly:

# List stacks
curl -X POST http://localhost:8765/tools/list_stacks \
  -H "Content-Type: application/json" \
  -d '{}'

# Get server info
curl http://localhost:8765/server-info

Check Docker Compose Files

# Validate compose file
docker compose -f /srv/dockerdata/stack-name/docker-compose.yml config

# Test without starting
docker compose -f /srv/dockerdata/stack-name/docker-compose.yml up --no-start

Network Debugging

# List networks
docker network ls

# Inspect network
docker network inspect traefik_proxy

# Test connectivity
docker run --rm --network traefik_proxy alpine ping -c 4 container_name

Error Reference

Common Error Messages

Error Cause Solution
Stack already exists Duplicate name Use different name or remove existing
Port is already allocated Port conflict Use different port or stop conflicting service
No such image Image not found Check image name and registry
Network not found Missing network Create network: docker network create traefik_proxy
Permission denied Docker permissions Add user to docker group
Invalid compose file YAML syntax error Check indentation and syntax
DNS record exists Duplicate DNS Use different subdomain or update existing
Cloudflare API error Invalid credentials Check API token and permissions

MCP-Specific Errors

Error Cause Solution
Tool not found MCP not loaded Restart Claude Desktop
Invalid parameters Wrong tool usage Check tool documentation
Timeout waiting for response Server not responding Check if StackWiz MCP is running
Connection refused Server not started Start StackWiz MCP server

Getting Help

1. Diagnostic Information

When reporting issues, include: 

# System info
uname -a
python --version
docker --version

# StackWiz info
cd /srv/dockerdata/stackwiz-mcp
git log -1 --oneline

# Error logs
tail -n 50 ~/.cache/stackwiz-mcp/logs/server.log

2. Test in Isolation

# Create minimal test
cd /tmp
cat > test-compose.yml << EOF
version: '3.8'
services:
  test:
    image: nginx:alpine
    ports:
      - "8888:80"
EOF

docker compose -f test-compose.yml up

3. Check Documentation

Prevention Tips

1. Regular Maintenance

# Weekly cleanup
docker system prune -a --volumes
docker image prune -a

2. Monitor Resources

Ask Claude periodically:

"Show me resource usage for all stacks" "Which services are using the most memory?"

3. Backup Configurations

# Backup all stack configs
tar -czf stacks-backup.tar.gz /srv/dockerdata/*/docker-compose.yml

4. Keep Updated

# Update StackWiz MCP
cd /srv/dockerdata/stackwiz-mcp
git pull
pip install -e . --upgrade

Emergency Recovery

If Everything Breaks

  1. Stop All Services: 

    docker stop $(docker ps -q)

  2. Restart Docker: 

    sudo systemctl restart docker

  3. Start Essential Services: 

    cd /srv/dockerdata/traefik && docker compose up -d

  4. Start Services One by One: Ask Claude:

    "List all stacks and start them one by one, checking for errors"

Restore from Backup

If you have infrastructure backups: 

# Restore from R2 backup
/srv/dockerdata/rclone/restore-infrastructure.sh

Next Steps