Troubleshooting

Installation Issues

Python Package Installation Fails

Error: Could not install packages due to an EnvironmentError

Problem: Permission denied when installing social-analyzer.Solution:

# Use pip with --user flag
pip3 install --user social-analyzer

Or install with sudo (not recommended for security):

sudo pip3 install social-analyzer

ModuleNotFoundError: No module named 'social-analyzer'

Problem: Python cannot find the installed module.Solution:

Ensure you installed for the correct Python version:
```
python3 -m pip install social-analyzer
```
Check your Python path:
```
python3 -m site
```

Run directly with python -m:

python3 -m social-analyzer --username "johndoe"

Node.js Installation Issues

npm install fails with dependency errors

Problem: Package dependencies cannot be resolved.Solution:

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

Error: Cannot find module 'express'

Problem: Required Node.js modules are missing.Solution:

cd social-analyzer
npm update
npm install

Runtime Errors

Browser and WebDriver Issues

selenium.common.exceptions.WebDriverException: Message: 'geckodriver' executable needs to be in PATH

Problem: Firefox WebDriver (geckodriver) is not installed or not in system PATH.Solution:Linux:

sudo apt-get install firefox-esr

macOS:

brew install geckodriver

Manual installation:

Download geckodriver from https://github.com/mozilla/geckodriver/releases

Extract and move to /usr/local/bin:

sudo mv geckodriver /usr/local/bin/
sudo chmod +x /usr/local/bin/geckodriver

Screenshots not working

Problem: Screenshot feature fails or produces blank images.Solution:

Ensure Chrome/Chromium is installed:

# Linux
sudo apt-get install chromium-browser

# macOS
brew install --cask google-chrome

Update to the latest Chrome version
Try without headless mode (modify in code)

Check for error messages in logs:

python3 -m social-analyzer --username "johndoe" --screenshots --logs

Screenshots require the latest version of Chrome or Chromium. Outdated browsers may cause the screenshot feature to fail silently.

OCR and Tesseract Issues

TesseractNotFoundError: tesseract is not installed or it's not in your PATH

Problem: Tesseract OCR is not installed.Solution:Linux:

sudo apt-get install tesseract-ocr

macOS:

brew install tesseract

Windows: Download and install from: https://github.com/UB-Mannheim/tesseract/wiki

Network and Connection Issues

Connection timeout errors

Problem: Requests are timing out when checking websites.Solution:

Increase timeout value:

python3 -m social-analyzer --username "johndoe" --timeout 15

Check your internet connection
Use a VPN if websites are geo-blocked
Some sites may be temporarily down - retry later

Too many failed profiles

Problem: Most searches return “failed” status.Solution:

Websites may be blocking automated requests. Try:
- Using a proxy
- Reducing number of workers
- Increasing timeout

Filter to only see detected profiles:

python3 -m social-analyzer --username "johndoe" --profiles "detected"

Some websites may have changed their structure (updates needed)

Cloudflare or CAPTCHA blocking requests

Problem: Error messages like “Attention Required” or “Cloudflare” in results.Solution:

This is expected for some websites with anti-bot protection
The web app interface (not CLI) may handle CAPTCHAs better:
```
npm start
# Open http://localhost:9005/app.html
```

Use mode options to avoid heavy detection:

python3 -m social-analyzer --username "johndoe" --mode "fast"

Consider using proxies for affected sites

Some websites actively block automated tools. Social Analyzer includes WAF detection, but may still be blocked by advanced protection systems like Cloudflare.

Output and Results Issues

No results returned

Problem: Search completes but no profiles detected.Solution:

Try with --filter "all" to see all results:

python3 -m social-analyzer --username "johndoe" --filter "all" --profiles "all"

Check username spelling and format

Try variations of the username:

python3 -m social-analyzer --username "johndoe,john_doe,john.doe"

Verify internet connectivity

JSON output is malformed

Problem: JSON output cannot be parsed.Solution:

Ensure silent mode when using JSON:

results = SocialAnalyzer.run_as_object(username="johndoe", silent=True)

Use output redirection properly:

python3 -m social-analyzer --username "johndoe" --output "json" --silent > results.json

Check for error messages mixed in output

Docker Issues

Docker container exits immediately

Problem: Container starts then stops.Solution:

Check container logs:
```
docker logs <container_id>
```
Ensure port 9005 is not already in use:
```
lsof -i :9005
```

Try a different port:

docker run -p 9006:9005 qeeqbox/social-analyzer

Cannot access web interface at localhost:9005

Problem: Web interface is not accessible.Solution:

Verify container is running:
```
docker ps
```
Check correct URL: http://localhost:9005/app.html
Try http://0.0.0.0:9005/app.html or http://127.0.0.1:9005/app.html
Check firewall settings

Docker compose grid mode not working

Problem: Grid mode fails or doesn’t improve performance.Solution:

Ensure docker-compose.yml is present:
```
ls -la docker-compose.yml
```
Check Docker Compose version:
```
docker-compose --version
```

Rebuild containers:

docker-compose down
docker-compose up --build

Performance Issues

Search is very slow

Problem: Searches take too long to complete.Solution:

Use --top to search fewer sites:

python3 -m social-analyzer --username "johndoe" --top 50

Target specific websites:

python3 -m social-analyzer --username "johndoe" --websites "github twitter"

Use fast mode:

python3 -m social-analyzer --username "johndoe" --mode "fast"

Increase worker count (requires code modification):
```
SocialAnalyzer.workers = 30
```

Reduce timeout:

python3 -m social-analyzer --username "johndoe" --timeout 5

High memory usage

Problem: Social Analyzer consumes too much RAM.Solution:

Reduce number of workers
Don’t use screenshot feature for many profiles
Process smaller batches of usernames
Close other applications
Search fewer websites at once

Metadata and Extraction Issues

Metadata extraction returns empty results

Problem: --metadata flag doesn’t extract information.Solution:

Ensure profiles are detected first
Metadata depends on profile structure - not all sites support it

Use with extract flag:

python3 -m social-analyzer --username "johndoe" --metadata --extract

Check if QeeqBox OSINT module is properly installed

Logging and Debugging

Logs are not being saved

Problem: Log files are not created despite using --logs.Solution:

Check permissions in temp directory

Specify custom log directory:

python3 -m social-analyzer --username "johndoe" --logs --logs_dir "./my_logs"

Ensure directory exists and is writable

Enable Debug Mode

For detailed troubleshooting information:

from importlib import import_module
import logging

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

SocialAnalyzer = import_module("social-analyzer").SocialAnalyzer(silent=False)
results = SocialAnalyzer.run_as_object(username="johndoe")

Common Error Messages

Error Message	Likely Cause	Solution
`ModuleNotFoundError`	Missing Python dependencies	Run `pip3 install -r requirements.txt`
`ConnectionError`	Network issues	Check internet connection, increase timeout
`WebDriverException`	Browser driver not found	Install geckodriver or chromedriver
`PermissionError`	Insufficient file permissions	Use `sudo` or change directory permissions
`JSONDecodeError`	Invalid API response	Website structure changed, needs update
`TimeoutError`	Request took too long	Increase `--timeout` value
`TesseractNotFoundError`	OCR not installed	Install tesseract-ocr package

Getting Help

If you’re still experiencing issues:

Check GitHub Issues: https://github.com/qeeqbox/social-analyzer/issues
Search for similar problems - your issue may already be solved
Open a new issue with:
- Your operating system
- Python/Node.js version
- Complete error message
- Steps to reproduce
- Command you ran

For issues related to private modules or modules ending in -private, contact the author directly. Do not open GitHub issues for private module problems.

Known Limitations

Some websites may require manual verification (CAPTCHAs)
Anti-bot systems may block automated requests
Detection accuracy varies by website structure
Screenshots require GUI environment (may fail in headless servers)
Rate limiting may occur on some platforms
Some countries may block certain social media sites

Keep Social Analyzer updated to benefit from the latest website detection patterns and bug fixes:

pip3 install --upgrade social-analyzer

Additional Info

Installation Issues

Python Package Installation Fails

Node.js Installation Issues

Runtime Errors

Browser and WebDriver Issues

OCR and Tesseract Issues

Network and Connection Issues

Output and Results Issues

Docker Issues

Performance Issues

Metadata and Extraction Issues

Logging and Debugging

Enable Debug Mode

Common Error Messages

Getting Help

Known Limitations

Build docs developers (and LLMs) love

Additional Info

​Installation Issues

​Python Package Installation Fails

​Node.js Installation Issues

​Runtime Errors

​Browser and WebDriver Issues

​OCR and Tesseract Issues

​Network and Connection Issues

​Output and Results Issues

​Docker Issues

​Performance Issues

​Metadata and Extraction Issues

​Logging and Debugging

​Enable Debug Mode

​Common Error Messages

​Getting Help

​Known Limitations

Build docs developers (and LLMs) love

Installation Issues

Python Package Installation Fails

Node.js Installation Issues

Runtime Errors

Browser and WebDriver Issues

OCR and Tesseract Issues

Network and Connection Issues

Output and Results Issues

Docker Issues

Performance Issues

Metadata and Extraction Issues

Logging and Debugging

Enable Debug Mode

Common Error Messages

Getting Help

Known Limitations