Troubleshooting¶

Solutions to common issues with recurl.

Installation Issues¶

"Command not found: recurl"¶

The binary is not in your PATH.

Solution:

# Add to PATH (Linux/macOS)
export PATH="/usr/local/recurl:$PATH"

# Or use full path
/usr/local/recurl/recurl --version

Alias Not Working¶

The shell alias may not be set up correctly.

Solution:

# Check if alias exists
alias curl

# Re-add alias
echo 'alias curl="/usr/local/recurl/recurl"' >> ~/.bashrc
source ~/.bashrc

Chromium Issues¶

"Chromium auto-download not available"¶

You're on Linux ARM64 where auto-download isn't supported.

Solution:

# Install Chromium manually
# Ubuntu/Debian:
sudo apt install chromium-browser

# Fedora:
sudo dnf install chromium

# Arch:
sudo pacman -S chromium

"Failed to launch browser"¶

Chromium couldn't start. Common causes:

1. Missing dependencies

   # Install dependencies (Debian/Ubuntu)
   sudo apt install -y \
       libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 \
       libxcomposite1 libxdamage1 libxrandr2 libgbm1 libasound2
   

2. No display (headless server)

   # Ensure using headless mode (default)
   # If issues persist, try:
   export DISPLAY=:0
   

3. Sandbox issues

   # recurl already uses --no-sandbox
   # If still failing, check permissions
   

"Chromium download timeout"¶

Network issues during Chromium download.

Solution:

# Retry with debug
recurl --recurl-debug --recurl-js https://example.com

# Or use system Chrome
# Install Chrome and recurl will find it

Request Issues¶

Still Getting 403 After Escalation¶

The site may have additional protections.

Try:

1. Force JS preflight

   recurl --recurl-js https://site.com
   

2. Wait for specific element

   recurl --recurl-js --recurl-js-wait ".content-loaded" https://site.com
   

3. Increase timeout

   recurl --recurl-js --recurl-js-timeout 60000 https://site.com
   

4. Check debug output

   recurl --recurl-debug --recurl-js https://site.com
   

Request Hangs¶

Possible timeout or infinite wait.

Solution:

# Set explicit timeout
recurl --recurl-js --recurl-js-timeout 30000 https://site.com

# Or use curl timeout
recurl --max-time 60 https://site.com

Wrong Content Returned¶

The page may require JavaScript rendering.

Solution:

# Get rendered HTML
recurl --recurl-js-rendered https://spa-site.com

# Wait for content
recurl --recurl-js-rendered --recurl-js-wait "#app-loaded" https://spa-site.com

Daemon Issues¶

"Failed to connect to daemon"¶

The daemon may not be running or socket is stale.

Solution:

# Remove stale socket (Linux/macOS)
rm /tmp/recurl.*.sock

# Try again
recurl --recurl-js https://example.com

Daemon Using Too Much Memory¶

The browser pool consumes memory.

Solution:

# Reduce idle timeout
export RCURL_DAEMON_IDLE_MS=10000

# Or disable daemon
recurl --recurl-daemon off --recurl-js https://example.com

Daemon Won't Stop¶

Force kill the daemon process.

Solution:

# Find and kill (Linux/macOS)
pkill -f recurld

# Windows
taskkill /IM recurld.exe /F

Performance Issues¶

Slow First Request¶

First JS preflight downloads Chromium and launches browser.

This is normal. Subsequent requests will be faster.

Slow Subsequent Requests¶

Daemon may not be running.

Check:

# See if daemon is active
ps aux | grep recurld

# Enable debug to see daemon usage
recurl --recurl-debug --recurl-js https://example.com

High CPU Usage¶

Browser automation is CPU-intensive.

Mitigations:

# Reduce daemon timeout
export RCURL_DAEMON_IDLE_MS=30000

# Disable daemon for one-off requests
recurl --recurl-daemon off --recurl-js https://example.com

Debug Mode¶

Always start troubleshooting with debug mode:

recurl --recurl-debug https://problematic-site.com

Debug output shows:

• Which engine was used
• Detection results
• Escalation steps
• Cookie extraction
• Final result

Combined with curl verbose¶

recurl --recurl-debug -v https://problematic-site.com

Shows both recurl decisions and curl network details.

Common Error Messages¶

Getting Help¶

Provide Debug Output¶

When reporting issues, include:

recurl --recurl-debug --recurl-js https://problematic-site.com 2>&1

Check Version¶

recurl --version

System Information¶

uname -a
which chromium google-chrome

Report Issues¶

Open an issue at GitHub Issues with:

1. recurl version
2. Operating system and architecture
3. Debug output
4. Steps to reproduce