Troubleshooting Guide

This is your comprehensive troubleshooting hub for the WhoisXML API MCP Server. Whether you're facing installation issues, configuration problems, or runtime errors, we have dedicated guides to help you resolve them quickly.

Quick Diagnosis

  1. Test the server independently before blaming integrations
  2. Check the basics: API token, network connectivity, file permissions
  3. Enable HTTP debugging to see what's actually happening
  4. Use the right guide based on your installation method and issue type

Quick Problem Identification

Server Won't Start

Server Starts But No Tools Appear

Authentication Failures

Performance Issues

Installation-Specific Troubleshooting

Choose the guide that matches your installation method:

🐳 Docker Troubleshooting

For container-related issues

Complete Docker Troubleshooting Guide →

Common Docker problems and solutions:

  • Container won't start or exits immediately
  • Environment variable issues
  • Port conflicts in HTTP server mode
  • Volume and file system problems
  • Network connectivity within containers
  • Platform-specific Docker issues

When to use: You're running the MCP server using Docker containers

📦 npm Troubleshooting

For Node.js and npm-related issues

Complete npm Troubleshooting Guide →

Common npm problems and solutions:

  • Package installation failures
  • Permission denied errors
  • Command not found issues
  • Node.js version compatibility
  • Corporate network and proxy problems
  • Runtime and configuration issues

When to use: You're running the MCP server via npm or npx

💾 Binary Troubleshooting

For standalone binary issues

Complete Binary Troubleshooting Guide →

Common binary problems and solutions:

  • File permissions and executable issues
  • macOS quarantine and security warnings
  • Architecture mismatch problems
  • Missing dependencies on Linux
  • Windows Defender and antivirus conflicts
  • PATH and configuration issues

When to use: You're running the MCP server as a downloaded binary

Client Integration Troubleshooting

🤖 AI Client Troubleshooting

For AI client integration issues

Complete AI Client Troubleshooting Guide →

Common AI client problems and solutions:

  • Tools not appearing in client
  • Configuration file issues
  • Client-specific integration problems
  • Authentication and token issues
  • Performance and scaling issues
  • Client crashes or timeouts

Covers these clients:

  • Claude Desktop
  • Cursor IDE
  • Claude Code CLI
  • Gemini CLI tools
  • VS Code extensions
  • Other MCP-compatible clients

When to use: The server works independently but doesn't integrate properly with your AI client

Network and API Troubleshooting

🌐 HTTP Debugging

For network, API, and performance issues

Complete HTTP Debugging Guide →

Comprehensive HTTP debugging and network troubleshooting:

  • HTTP request/response logging
  • Network connectivity problems
  • DNS resolution issues
  • SSL/TLS certificate problems
  • API authentication failures
  • Rate limiting and timeout issues
  • Performance analysis and optimization

When to use:

  • API calls are failing
  • Network connectivity issues
  • Slow performance or timeouts
  • Authentication problems
  • Need to debug actual HTTP requests

Common Error Messages

"API key token environment variable is required"

Cause: The WHOISXMLAPI_TOKEN environment variable is not set or not accessible.

Solutions:

  1. Check environment variable:

    echo $WHOISXMLAPI_TOKEN

  2. Set environment variable:

    export WHOISXMLAPI_TOKEN="your-token-here"

  3. Check client configuration:

    {
  "env": {
    "WHOISXMLAPI_TOKEN": "your-token-here"
  }
}

More help: HTTP Debugging

"Connection refused" or "Network unreachable"

Cause: Network connectivity issues between the server and WhoisXMLAPI.

Solutions:

  1. Test basic connectivity:

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

  2. Check proxy settings (corporate networks)

  3. Verify firewall rules allow outbound HTTPS

More help: HTTP Debugging

"Command not found" or "No such file or directory"

Cause: Binary installation or PATH issues.

Solutions:

  1. Check file exists and is executable:

    ls -la mcp-whoisxmlapi
chmod +x mcp-whoisxmlapi

  2. Use absolute paths in configuration

  3. Install to system PATH

More help: Binary Troubleshooting

"Permission denied"

Cause: File permissions or system access issues.

Solutions based on installation method:

AI Client Doesn't See MCP Server

Cause: Client configuration or integration issues.

Solutions:

  1. Restart client completely after configuration changes
  2. Check JSON syntax in configuration files
  3. Verify server works independently

More help: AI Client Troubleshooting

General Debugging Steps

1. Test Server Independently

Before debugging client integration, verify the server works:

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

# npm test
npx @whoisxmlapidotcom/mcp-whoisxmlapi --help

# Binary test
./mcp-whoisxmlapi --help

2. Enable HTTP Debugging

Get detailed information about API calls:

export WHOISXMLAPI_HTTP_DEBUG="/tmp/whoisxmlapi-debug.log"
# Then run your server and check the log file
tail -f /tmp/whoisxmlapi-debug.log

3. Check Configuration Syntax

Validate JSON configuration files:

# Validate JSON syntax
python -m json.tool your-config.json
# or
jq . your-config.json

4. Verify API Token

Test your token directly:

curl -H "Authorization: Bearer $WHOISXMLAPI_TOKEN" \
  "https://www.whoisxmlapi.com/api/v1/account-balance"

5. Check System Requirements

Ensure your system meets the requirements:

  • Docker: Docker installed and running
  • npm: Node.js 22+ LTS installed
  • Binary: Correct architecture and permissions

Getting Additional Help

Information to Collect

When seeking help, provide:

  1. Installation method (Docker, npm, or binary)
  2. Operating system and version
  3. AI client being used
  4. Complete error messages
  5. Configuration file (remove API token)
  6. HTTP debug logs (if available)

Testing Commands

Run these commands and include the output:

# System information
uname -a
echo "Installation method: [Docker/npm/binary]"

# Server test
# [Use appropriate command for your installation method]

# Configuration test
python -m json.tool your-config.json

# Network test
ping whoisxmlapi.com
curl -I https://whoisxmlapi.com

Where to Get Help

  1. Check the appropriate troubleshooting guide based on your issue type
  2. Review error messages and match them to common solutions
  3. Enable debugging to get more detailed information
  4. Contact support with complete debugging information

Prevention Tips

Regular Maintenance

  1. Keep software updated:

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

# Update npm packages
npm update -g @whoisxmlapidotcom/mcp-whoisxmlapi

# Download latest binary
# Check releases page for updates

  2. Monitor logs regularly:

    # Check for errors in HTTP debug logs
grep -i error /tmp/whoisxmlapi-debug.log

  3. Test configuration changes:

    # Always test server independently after changes
mcp-whoisxmlapi --help

Best Practices

  1. Use absolute paths in configuration files
  2. Keep API tokens secure and rotate regularly
  3. Enable logging when troubleshooting
  4. Test one change at a time when debugging
  5. Restart clients completely after configuration changes
Last Updated: