Troubleshooting

Common Errors

No undetected chromedriver binary were found

Error Message:

No undetected chromedriver binary were found.
Call `Patcher.patch()` outside of multiprocessing/threading implementation.

Cause: You’re using multiprocessing without properly initializing the patcher.Solution:Call Patcher.patch() before spawning processes and use user_multi_procs=True:

import undetected as uc
from undetected.patcher import Patcher
import multiprocessing as mp

def worker():
    driver = uc.Chrome(user_multi_procs=True)  # Important!
    driver.get("https://example.com")
    driver.quit()

if __name__ == "__main__":
    Patcher.patch()  # Call this FIRST
    
    processes = [mp.Process(target=worker) for _ in range(4)]
    for p in processes:
        p.start()
    for p in processes:
        p.join()

See Multiprocessing Setup for more details.

you cannot reuse the ChromeOptions object

Error Message:

RuntimeError: you cannot reuse the ChromeOptions object

Cause: Attempting to use the same ChromeOptions instance for multiple drivers.Solution:Create a new options object for each driver:

import undetected as uc

# ❌ WRONG
options = uc.ChromeOptions()
driver1 = uc.Chrome(options=options)
driver2 = uc.Chrome(options=options)  # Error!

# ✅ CORRECT
options1 = uc.ChromeOptions()
driver1 = uc.Chrome(options=options1)

options2 = uc.ChromeOptions()
driver2 = uc.Chrome(options=options2)

PermissionError when accessing chromedriver

Error Message:

PermissionError: [Errno 13] Permission denied: '~/.local/share/undetected/chromedriver'

Cause: Multiple processes are trying to modify the same binary file, or the file is still in use.Solutions:

For multiprocessing: Use user_multi_procs=True

driver = uc.Chrome(user_multi_procs=True)

For single process: Ensure previous driver is properly closed

driver1 = uc.Chrome()
driver1.quit()  # Ensure quit is called

driver2 = uc.Chrome()  # Now safe to create new instance

Manual cleanup:

from undetected.patcher import Patcher
Patcher.cleanup_unused_files()

Chrome fails to start as root

Error Message:

Running as root without --no-sandbox is not supported

Cause: Chrome refuses to run as root without the --no-sandbox flag.Solution:The library adds this automatically by default. If you’re still seeing this, ensure you haven’t disabled it:

import undetected as uc

# This is the default behavior
driver = uc.Chrome(no_sandbox=True)

# Or add it explicitly via options
options = uc.ChromeOptions()
options.add_argument("--no-sandbox")
options.add_argument("--disable-dev-shm-usage")
driver = uc.Chrome(options=options)

Better solution: Don’t run as root. Create a dedicated user:

sudo useradd -m scraper
sudo -u scraper python your_script.py

SessionNotCreatedException: session not created

Error Message:

selenium.common.exceptions.SessionNotCreatedException: Message: session not created: 
This version of ChromeDriver only supports Chrome version X

Cause: ChromeDriver version doesn’t match your Chrome browser version.Solution:Undetected automatically downloads the correct version. This error usually indicates:

Manual driver path specified incorrectly:

# Let the library handle it automatically
driver = uc.Chrome()  # Don't specify driver_executable_path

Unusual Chrome installation location:

driver = uc.Chrome(
    browser_executable_path="/path/to/chrome"
)

Force re-download:

from undetected.patcher import Patcher
Patcher.cleanup_unused_files()
# Then create driver normally
driver = uc.Chrome()

Browser detected as bot

Symptom: Your browser is still being detected by Cloudflare, DataDome, or other anti-bot systems.Possible Causes & Solutions:

Too many customizations:

# ❌ AVOID heavy customization
options = uc.ChromeOptions()
options.add_argument("--user-agent=...")  # Don't override UA
options.add_extension("extension.crx")    # Avoid extensions

# ✅ BETTER - use defaults
driver = uc.Chrome()  # Minimal customization

Headless mode:

# Headless mode lowers undetectability
# Use only when necessary
driver = uc.Chrome(headless=False)  # Prefer visible mode

Behavioral patterns:

import time
import random

driver = uc.Chrome()
driver.get("https://example.com")

# Add human-like delays
time.sleep(random.uniform(1, 3))

# Natural scrolling
driver.execute_script("window.scrollTo(0, document.body.scrollHeight/2);")
time.sleep(random.uniform(0.5, 1.5))

IP reputation:

Use residential proxies instead of datacenter IPs
Rotate IP addresses
Respect rate limits

Temp profile not deleted

Symptom: Temporary user data directories accumulate in /tmp or AppData.Cause: Driver not properly closed with quit().Solution:Always call quit() using try/finally:

import undetected as uc

driver = uc.Chrome()
try:
    driver.get("https://example.com")
    # ... do work ...
finally:
    driver.quit()  # Ensures cleanup

Manual cleanup:

# Linux/macOS
rm -rf /tmp/tmp*

# Windows PowerShell
Remove-Item -Path "$env:TEMP\tmp*" -Recurse -Force

Could not connect to Chrome

Error Message:

selenium.common.exceptions.WebDriverException: Message: chrome not reachable

Causes & Solutions:

Chrome crashed during startup:

# Add more memory if running in containers
options = uc.ChromeOptions()
options.add_argument("--disable-dev-shm-usage")
driver = uc.Chrome(options=options)

Port already in use:

# Let the library choose a free port
driver = uc.Chrome(port=0)  # 0 = auto-select

Firewall blocking:

Check that localhost/127.0.0.1 is not blocked
Ensure Chrome can bind to random high ports

TimeoutException during page load

Error Message:

selenium.common.exceptions.TimeoutException: Message: timeout

Solutions:

Increase page load timeout:

import undetected as uc

driver = uc.Chrome()
driver.set_page_load_timeout(30)  # 30 seconds
driver.get("https://slow-site.com")

Use eager loading strategy:

options = uc.ChromeOptions()
options.set_capability("pageLoadStrategy", "eager")
driver = uc.Chrome(options=options)

Wait for specific elements instead:

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By

driver = uc.Chrome()
driver.get("https://example.com")

element = WebDriverWait(driver, 10).until(
    EC.presence_of_element_located((By.ID, "content"))
)

Platform-Specific Issues

Linux

Missing shared libraries

Error: error while loading shared libraries: libnss3.soSolution:

# Debian/Ubuntu
sudo apt-get install -y \
  libnss3 \
  libgconf-2-4 \
  libfontconfig1 \
  libxss1 \
  libappindicator1 \
  libasound2

# RHEL/CentOS
sudo yum install -y \
  nss \
  alsa-lib \
  liberation-fonts

Display issues in headless environments

Error: Could not initialize GTKSolution:

# Install virtual display
sudo apt-get install -y xvfb

# Use with Xvfb
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
python your_script.py

Or use headless mode:

driver = uc.Chrome(headless=True)

Windows

Antivirus blocking ChromeDriver

Symptom: ChromeDriver is deleted or quarantined immediately after download.Solution:Add exception for the undetected data directory:

Default location: %APPDATA%\Roaming\undetected
Add to antivirus exclusions

Path too long error

Error: OSError: [WinError 206] The filename or extension is too longSolution:

# Use shorter user_data_dir path
driver = uc.Chrome(user_data_dir="C:/temp/uc")

Or enable long paths in Windows:

# Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

macOS

macOS Gatekeeper blocking ChromeDriver

Error: "chromedriver" cannot be opened because the developer cannot be verifiedSolution:

# Find the ChromeDriver location
ls ~/Library/Application\ Support/undetected/

# Remove quarantine attribute
xattr -d com.apple.quarantine ~/Library/Application\ Support/undetected/*chromedriver*

Docker Issues

Running in Docker containers

Common issues: Shared memory, display, Chrome installationSolution:Use this Dockerfile template:

FROM python:3.11-slim

# Install Chrome dependencies
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    ca-certificates \
    fonts-liberation \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libatspi2.0-0 \
    libcups2 \
    libdbus-1-3 \
    libdrm2 \
    libgbm1 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libwayland-client0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxkbcommon0 \
    libxrandr2 \
    xdg-utils \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

# Install Chrome
RUN wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
    && echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list \
    && apt-get update \
    && apt-get install -y google-chrome-stable \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "your_script.py"]

Python code:

import undetected as uc

options = uc.ChromeOptions()
options.add_argument("--no-sandbox")
options.add_argument("--disable-dev-shm-usage")
options.add_argument("--disable-gpu")

driver = uc.Chrome(options=options, headless=True)

Performance Issues

Slow page loads

Solutions:

Disable images:

options = uc.ChromeOptions()
prefs = {"profile.managed_default_content_settings.images": 2}
options.set_experimental_option("prefs", prefs)
driver = uc.Chrome(options=options)

Use eager loading:

options.set_capability("pageLoadStrategy", "eager")

Disable unnecessary features:

options.add_argument("--disable-extensions")
options.add_argument("--disable-plugins")
options.add_argument("--disable-blink-features=AutomationControlled")

High memory usage

Solutions:

Limit concurrent instances:

# Don't run too many browsers at once
MAX_CONCURRENT = 4  # Adjust based on your system

Use headless mode:

driver = uc.Chrome(headless=True)

Clean up properly:

driver.quit()  # Always call quit()

Increase Docker memory limit:

docker run --memory="2g" your_image

Debugging Tips

Enable Debug Logging

import logging
import undetected as uc

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

driver = uc.Chrome(debug=True)

Save Screenshots on Error

import undetected as uc

driver = uc.Chrome()
try:
    driver.get("https://example.com")
    # ... your code ...
except Exception as e:
    driver.save_screenshot("error.png")
    print(f"Error: {e}")
    raise
finally:
    driver.quit()

Check Chrome Version

import undetected as uc

driver = uc.Chrome()
driver.get("chrome://version")
driver.save_screenshot("chrome_version.png")

# Check ChromeDriver version
print(driver.capabilities['chrome']['chromedriverVersion'])

driver.quit()

Test Bot Detection

import undetected as uc

driver = uc.Chrome()

# Test sites
test_urls = [
    "https://bot.incolumitas.com",
    "https://nowsecure.nl",
    "https://arh.antoinevastel.com/bots/areyouheadless",
]

for url in test_urls:
    driver.get(url)
    driver.save_screenshot(f"test_{url.split('//')[-1].replace('/', '_')}.png")
    input(f"Check {url} - Press Enter to continue...")

driver.quit()

Getting Help

If you’re still experiencing issues:

Check the GitHub issues: undetected-chromedriver issues
Provide details: Chrome version, OS, Python version, full error traceback
Minimal reproducible example: Simplify your code to the minimum that reproduces the issue

Next Steps

Review Basic Usage for correct patterns
Check Multiprocessing Setup for concurrent execution
Explore Custom Options for configuration details

Get Started

Core Concepts

Advanced Features

Guides

Common Errors

Platform-Specific Issues

Linux

Windows

macOS

Docker Issues

Performance Issues

Debugging Tips

Enable Debug Logging

Save Screenshots on Error

Check Chrome Version

Test Bot Detection

Getting Help

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Advanced Features

Guides

​Common Errors

​Platform-Specific Issues

​Linux

​Windows

​macOS

​Docker Issues

​Performance Issues

​Debugging Tips

​Enable Debug Logging

​Save Screenshots on Error

​Check Chrome Version

​Test Bot Detection

​Getting Help

​Next Steps

Build docs developers (and LLMs) love

Common Errors

Platform-Specific Issues

Linux

Windows

macOS

Docker Issues

Performance Issues

Debugging Tips

Enable Debug Logging

Save Screenshots on Error

Check Chrome Version

Test Bot Detection

Getting Help

Next Steps