Troubleshooting - JinsongRoh/pydoll-mcp GitHub Wiki

🔍 Troubleshooting Guide

A comprehensive guide for common issues and solutions when using PyDoll MCP Server.

📋 Table of Contents

🚨 Emergency Solutions

Top 5 Most Common Issues

1. Browser Won't Start

Quick Fix:

# Check browser path
python -c "from pydoll.browser import Chrome; print('Browser check successful')"

# Verify permissions and retry
python -m pydoll_mcp.cli test-browser --browser chrome

2. Claude Desktop MCP Connection Failed

Quick Fix:

# Auto reset
python -m pydoll_mcp.cli auto-setup --force

# Claude Desktop restart required

3. JSON Parsing Error (Fixed in v1.1.3)

Quick Fix:

# Upgrade to latest version
pip install --upgrade pydoll-mcp

# Check configuration
python -m pydoll_mcp.server --test

4. Korean Windows Encoding Issue

Quick Fix:

set PYTHONIOENCODING=utf-8
python -m pydoll_mcp.server

5. Permission Denied Error

Quick Fix:

# User installation
pip install --user pydoll-mcp

# Or run with administrator privileges

⚙️ Installation Issues

Python Version Issues

Symptoms

  • Python 3.8+ required error
  • Old Python version warnings

Solution

# Check Python version
python --version

# Upgrade required if below Python 3.8
# Windows: Install latest version from python.org
# macOS: brew install [email protected]
# Linux: sudo apt install python3.9

pip Upgrade Required

Symptoms

  • pip is outdated warning
  • Installation failure

Solution

# Upgrade pip
python -m pip install --upgrade pip

# Retry installation
pip install pydoll-mcp

# Install with verbose logging
pip install pydoll-mcp -v

Network Connection Issues

Symptoms

  • Connection timeout error
  • Failed to download message

Solution

# Increase timeout
pip install --timeout 120 pydoll-mcp

# Use alternative index
pip install -i https://pypi.org/simple/ pydoll-mcp

# Use proxy (if needed)
pip install --proxy http://proxy.company.com:8080 pydoll-mcp

Dependency Conflicts

Symptoms

  • Dependency conflict error
  • Package version compatibility issues

Solution

# Create virtual environment (recommended)
python -m venv pydoll-env
source pydoll-env/bin/activate  # Linux/macOS
pydoll-env\Scripts\activate     # Windows

# Clean installation
pip install pydoll-mcp

# Force upgrade dependencies
pip install --upgrade --force-reinstall pydoll-mcp

🔗 Claude Desktop Integration Issues

MCP Server Not Recognized

Symptoms

  • MCP icon doesn't appear in Claude Desktop
  • Browser automation commands don't work

Diagnosis

# Check config file location
python -m pydoll_mcp.cli status --config

# Check config file content
cat ~/.config/Claude/claude_desktop_config.json  # Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json  # macOS
type %APPDATA%\Claude\claude_desktop_config.json  # Windows

Solution

# 1. Auto reset
python -m pydoll_mcp.cli auto-setup --force

# 2. Manual configuration check
python -m pydoll_mcp.cli generate-config --check

# 3. Restore backup (if needed)
python -m pydoll_mcp.cli restore-config

# 4. Complete Claude Desktop restart

Configuration File Format Error

Symptoms

  • Invalid JSON format error
  • Claude Desktop startup failure

Solution

# Validate JSON format
python -m json.tool ~/.config/Claude/claude_desktop_config.json

# Regenerate config file
python -m pydoll_mcp.cli generate-config --backup

# Restore to default settings
python -m pydoll_mcp.cli reset-config

Permission Issues

Symptoms

  • Permission denied error
  • Config file write failure

Solution

# Check file permissions
ls -la ~/.config/Claude/claude_desktop_config.json

# Fix permissions (Linux/macOS)
chmod 644 ~/.config/Claude/claude_desktop_config.json

# Check directory permissions
chmod 755 ~/.config/Claude/

🌐 Browser-Related Issues

Chrome Browser Startup Failure

Symptoms

  • ChromeDriver not found error
  • Browser window won't open

Diagnosis

# Check Chrome installation
google-chrome --version          # Linux
chrome.exe --version             # Windows
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version  # macOS

# Check browser path
python -c "
from pydoll.browser import Chrome
browser = Chrome()
print(f'Chrome path: {browser.executable_path}')
"

Solution

# 1. Reinstall Chrome (if needed)
# Windows: Download from Google official site
# macOS: brew install --cask google-chrome
# Linux: wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -

# 2. Test browser
python -m pydoll_mcp.cli test-browser --browser chrome --verbose

# 3. Use alternative browser
python -m pydoll_mcp.cli test-browser --browser edge

Headless Mode Issues

Symptoms

  • Some features don't work in headless mode
  • Screenshots are empty

Solution

# Test with headless mode disabled
python -c "
from pydoll.browser import Chrome
browser = Chrome(headless=False)
browser.start()
browser.navigate('https://example.com')
browser.take_screenshot('test.png')
browser.stop()
"

# Use virtual display (Linux)
sudo apt install xvfb
export DISPLAY=:99
Xvfb :99 -screen 0 1920x1080x24 &

Browser Crashes and Zombie Processes

Symptoms

  • Browser becomes unresponsive
  • Multiple Chrome processes remain

Solution

# 1. Kill all browser processes
# Windows
taskkill /F /IM chrome.exe
taskkill /F /IM msedge.exe

# Linux/macOS
pkill -f chrome
pkill -f "Google Chrome"

# 2. Clean browser data directory
python -m pydoll_mcp.cli cleanup --browser-data

# 3. Start with new profile
python -c "
from pydoll.browser import Chrome
browser = Chrome(user_data_dir='/tmp/chrome_test')
browser.start()
"

🔤 Encoding and Language Issues

Korean Windows CP949 Issue

Symptoms

  • UnicodeEncodeError: 'cp949' error
  • Korean text appears garbled

Solution (Fixed in v1.1.3)

# 1. Set environment variables
set PYTHONIOENCODING=utf-8
set LANG=ko_KR.UTF-8

# 2. Change code page
chcp 65001

# 3. Add environment variables to Claude Desktop config
{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "LANG": "ko_KR.UTF-8"
      }
    }
  }
}

# 4. Permanent setting
setx PYTHONIOENCODING "utf-8"

Other Internationalization Issues

Symptoms

  • Non-English characters not displayed
  • Issues with multilingual websites

Solution

# 1. Check system locale
locale  # Linux/macOS
echo $LANG

# 2. Set UTF-8 locale
export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

# 3. Set browser language preferences
python -c "
from pydoll.browser import Chrome
browser = Chrome()
browser.set_preference('intl.accept_languages', 'ko-KR,ko,en-US,en')
"

🚀 Performance Issues

Slow Response Times

Symptoms

  • Very slow page loading
  • Commands take a long time to execute

Diagnosis

# Performance analysis
python -m pydoll_mcp.cli analyze-performance

# Network speed test
python -c "
from pydoll.browser import Chrome
browser = Chrome()
browser.start()
import time
start = time.time()
browser.navigate('https://www.google.com')
print(f'Load time: {time.time() - start:.2f}s')
"

Solution

# 1. Performance optimization settings
python -c "
from pydoll.browser import Chrome
browser = Chrome(
    headless=True,
    disable_images=True,
    disable_css=False,
    block_ads=True,
    enable_compression=True
)
"

# 2. Check network conditions
# 3. Check system resources
python -m pydoll_mcp.cli status --system

Excessive Memory Usage

Symptoms

  • System becomes slow
  • Out of memory errors

Solution

# 1. Monitor memory usage
python -m pydoll_mcp.cli status --memory

# 2. Adjust browser options
python -c "
from pydoll.browser import Chrome
browser = Chrome(
    max_memory_mb=512,
    disable_extensions=True,
    single_process=True
)
"

# 3. Force garbage collection
python -c "
import gc
gc.collect()
"

🛡️ Security and Access Issues

CAPTCHA Resolution Failure

Symptoms

  • Cloudflare captcha not resolved
  • reCAPTCHA bypass failed

Solution

# 1. Activate stealth mode
python -c "
from pydoll.browser import Chrome
browser = Chrome(stealth_mode=True)
browser.enable_stealth_mode()
"

# 2. Enhanced human behavior simulation
python -c "
browser.simulate_human_behavior(
    mouse_movement=True,
    typing_delays=True,
    scroll_behavior=True
)
"

# 3. User agent rotation
python -c "
browser.rotate_user_agent()
browser.randomize_fingerprint()
"

Bot Detection

Symptoms

  • "Automated traffic detected" message
  • Access blocked

Solution

# 1. Full stealth mode
python -c "
browser.enable_full_stealth_mode()
browser.evade_detection()
"

# 2. Use proxy
python -c "
browser.set_proxy('proxy.example.com:8080')
browser.rotate_proxy()
"

# 3. Adjust request intervals
python -c "
import time
time.sleep(2)  # Wait between requests
"

📱 Platform-Specific Issues

Windows-Specific Issues

PowerShell Execution Policy Issue

# Check execution policy
Get-ExecutionPolicy

# Change execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows Defender Interference

# Add Windows Defender exception
# Settings > Update & Security > Windows Security > Virus & threat protection
# Add Python installation directory to exceptions

macOS-Specific Issues

Gatekeeper Issues

# Check System Integrity Protection
csrutil status

# Allow developer tools permissions
sudo xcode-select --install

Permission Issues

# Grant Terminal full disk access permissions
# System Preferences > Security & Privacy > Privacy > Full Disk Access

Linux-Specific Issues

Display Server Issues

# Check X11 display server
echo $DISPLAY

# Switch from Wayland to X11
sudo apt install xorg
# Logout and login to X11 session

Library Dependencies

# Install required libraries
sudo apt update
sudo apt install -y \
    libnss3-dev \
    libgconf-2-4 \
    libxrandr2 \
    libasound2-dev \
    libpangocairo-1.0-0 \
    libatk1.0-dev \
    libcups2-dev \
    libdrm2 \
    libgtk-3-dev \
    libxss1

🔧 Advanced Troubleshooting

Enable Debug Mode

Detailed Logging Setup

# Set environment variables
export PYDOLL_DEBUG=1
export PYDOLL_LOG_LEVEL=DEBUG

# Or in Python code
import logging
logging.basicConfig(level=logging.DEBUG)

Log File Analysis

# Check log file location
python -m pydoll_mcp.cli status --logs

# Real-time log monitoring
tail -f ~/.pydoll/logs/pydoll.log

Network Issue Diagnosis

Connection Testing

# Basic connection test
curl -I https://www.google.com

# DNS resolution test
nslookup google.com

# Port connection test
telnet google.com 80

Proxy Settings Check

# Check proxy environment variables
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY

# Test without proxy settings
unset HTTP_PROXY HTTPS_PROXY

Deep System Diagnosis

System Resource Check

# CPU usage
top

# Memory usage
free -h

# Disk space
df -h

# Process check
ps aux | grep chrome
ps aux | grep python

File System Permissions

# Check file permissions
ls -la ~/.pydoll/
ls -la ~/.config/Claude/

# Fix permissions
chmod -R 755 ~/.pydoll/
chmod 644 ~/.config/Claude/claude_desktop_config.json

📞 Getting Additional Help

1. Automated Diagnostic Tools

# Run comprehensive diagnosis
python -m pydoll_mcp.cli diagnose --full

# Problem-specific diagnosis
python -m pydoll_mcp.cli diagnose --browser
python -m pydoll_mcp.cli diagnose --network
python -m pydoll_mcp.cli diagnose --config

2. Report Issues

If issues persist:

3. Community Support

Issue not resolved? 🤔
FAQ | Support | Bug Report

Most issues are resolved by upgrading to the latest version! 🚀

⚠️ **GitHub.com Fallback** ⚠️