Known Issues - JinsongRoh/pydoll-mcp GitHub Wiki

🚨 Known Issues

This page documents the currently known issues and their solutions for PyDoll MCP Server v1.1.3.

📋 Table of Contents

[Installation Issues](#installation-issues)
[Browser Issues](#browser-issues)
[Connection and Communication Issues](#connection-and-communication-issues)
[Encoding Issues](#encoding-issues)
[Configuration Issues](#configuration-issues)
[Performance Issues](#performance-issues)
[Platform-Specific Issues](#platform-specific-issues)

🔧 Installation Issues

Python Version Compatibility Issues

Issue: Installation fails on Python 3.7 or lower

ERROR: Package requires Python 3.8+

Solution:

# Check Python version
python --version

# Install Python 3.8+ and retry
pip install pydoll-mcp

pip Version Issues

Issue: Dependency installation fails due to outdated pip version

Solution:

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

# Reinstall with verbose output
pip install pydoll-mcp -v

Permission Issues (Linux/macOS)

Issue: Installation fails due to insufficient permissions

Solution:

# User installation
pip install --user pydoll-mcp

# Or use virtual environment
python -m venv venv
source venv/bin/activate
pip install pydoll-mcp

🌐 Browser Issues

Chrome/Chromium Path Issues

Issue: Chrome browser not found on system

BrowserNotFoundError: Chrome browser not found

Solution:

# Linux: Check Chrome installation
which google-chrome
ls -la /usr/bin/google-chrome

# macOS: Check Chrome path
ls "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# Windows: Check Chrome installation
where chrome.exe

Browser Permission Issues

Issue: Insufficient permissions to run browser (mainly in Linux server environments)

Solution:

# Check execution permissions
chmod +x /usr/bin/google-chrome

# Or run in headless mode
python -m pydoll_mcp.cli test-browser --headless

Browser Process Conflicts

Issue: Conflicts with existing browser processes

Solution:

# Terminate browser processes
pkill -f chrome
pkill -f chromium

# Re-run test
python -m pydoll_mcp.cli test-browser

🔗 Connection and Communication Issues

✅ MCP Communication Issues (Fixed in v1.1.3!)

Issue: MCP client communication failure due to JSON parsing errors

JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Solution (Completely fixed in v1.1.3):

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

# Verify fix
python -m pydoll_mcp.server --test

# Check that server output is clean JSON
python -m pydoll_mcp.cli status

Claude Desktop Connection Failure

Issue: Claude Desktop fails to recognize PyDoll MCP Server

Solution:

# Regenerate configuration
python -m pydoll_mcp.cli generate-config

# Restart Claude Desktop and check connection
python -m pydoll_mcp.cli status --logs

Port Conflict Issues

Issue: Conflicts with ports used by other processes

Solution:

# Check port usage
netstat -tulpn | grep :8080

# Terminate process and restart
kill -9 [PID]
python -m pydoll_mcp.server

🌍 Encoding Issues

✅ Korean Windows Encoding Issues (Fixed in v1.1.1!)

Issue: UnicodeEncodeError in Korean Windows environments (CP949/EUC-KR)

Solution (Completely fixed in v1.1.1):

# Resolved by upgrade
pip install --upgrade pydoll-mcp

# Set environment variable (additional assurance)
set PYTHONIOENCODING=utf-8
python -m pydoll_mcp.server

UTF-8 Encoding Issues

Issue: International character set processing errors

Solution:

# Windows: Change code page
chcp 65001

# Add environment variable to Claude Desktop configuration
{
  "mcpServers": {
    "pydoll": {
      "command": "python",
      "args": ["-m", "pydoll_mcp.server"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYDOLL_LOG_LEVEL": "INFO"
      }
    }
  }
}

⚙️ Configuration Issues

Claude Desktop Configuration File Path Issues

Issue: Cannot find configuration file location

Solution:

# Check configuration file path
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Linux: ~/.config/Claude/claude_desktop_config.json

# Re-run automatic setup
python -m pydoll_mcp.cli auto-setup --force

Configuration Backup Issues

Issue: Failure to backup existing configuration

Solution:

# Create manual backup
cp claude_desktop_config.json claude_desktop_config.json.backup

# Generate manual configuration
python -m pydoll_mcp.cli generate-config --auto-setup

Environment Variable Configuration Issues

Issue: Environment variables not properly applied

Solution:

# Check with debug mode
export PYDOLL_DEBUG=1
export PYDOLL_LOG_LEVEL=DEBUG
python -m pydoll_mcp.server --debug

⚡ Performance Issues

Excessive Memory Usage

Issue: Browser instances using too much memory

Solution:

# Optimize browser settings
{
  "browser_config": {
    "headless": true,
    "disable_images": true,
    "max_concurrent_tabs": 3
  }
}

# Run cleanup command
python -m pydoll_mcp.cli cleanup

Slow Response Times

Issue: Delays in web page loading and interactions

Solution:

# Optimize network settings
{
  "network_config": {
    "timeout": 15,
    "retry_attempts": 2,
    "enable_caching": true
  }
}

Browser Process Accumulation

Issue: Accumulation of unended browser processes

Solution:

# Clean up processes
pkill -f chrome
pkill -f pydoll

# Run cleanup script
python -m pydoll_mcp.cli cleanup

💻 Platform-Specific Issues

Windows-Specific Issues

PowerShell Execution Policy Issues

# Check execution policy
Get-ExecutionPolicy

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

Windows Defender Interference

Windows Defender may block browser automation
Need to add PyDoll MCP Server path to exclusion list

macOS-Specific Issues

Gatekeeper Security Issues

# Check security settings
spctl --status

# Allow Chrome execution permissions
xattr -d com.apple.quarantine "/Applications/Google Chrome.app"

System Permission Issues

Need to allow permissions in System Preferences > Security & Privacy > Accessibility

Linux-Specific Issues

Display Server Issues

# Check X11 server
echo $DISPLAY

# Run in X11 mode on Wayland environment
GDK_BACKEND=x11 python -m pydoll_mcp.server

Library Dependency Issues

# Install required libraries (Ubuntu/Debian)
sudo apt-get install -y \
    libnss3-dev \
    libgconf-2-4 \
    libxss1 \
    libasound2

# CentOS/RHEL
sudo yum install -y \
    nss \
    atk \
    at-spi2-atk \
    gtk3 \
    gdk-pixbuf2

🔍 Debugging Tools

Log Checking

# Check detailed logs
python -m pydoll_mcp.cli status --logs --stats

# Run in debug mode
python -m pydoll_mcp.server --debug

Installation Testing

# Verify installation status
python -m pydoll_mcp.cli test-installation --verbose

# Browser testing
python -m pydoll_mcp.cli test-browser --browser chrome --headless

Network Connection Testing

# MCP server connection test
python -m pydoll_mcp.server --test

# Check configuration status
python -m pydoll_mcp.cli status

🆘 Additional Support

Issue Reporting

If the problem is not resolved:

GitHub Issues: https://github.com/JinsongRoh/pydoll-mcp/issues

Collect debug information:

python -m pydoll_mcp.cli status --logs --stats > debug_info.txt

Include environment information:
- OS and version
- Python version
- PyDoll MCP Server version
- Browser version

Temporary Solutions

In case of serious issues:

# Complete reinstallation
pip uninstall pydoll-mcp
pip install pydoll-mcp

# Reset configuration
python -m pydoll_mcp.cli auto-setup --force

💡 Note: This document is based on v1.1.3, and some issues may have been resolved in newer versions. For the latest information, please check the [GitHub repository](https://github.com/JinsongRoh/pydoll-mcp).