Troubleshooting

Common issues and solutions for Social Analyzer

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:

1. Ensure you installed for the correct Python version:

   python3 -m pip install social-analyzer
   

2. Check your Python path:

   python3 -m site
   

3. 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:

1. Download geckodriver from https://github.com/mozilla/geckodriver/releases
2. 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:

1. Ensure Chrome/Chromium is installed:

   # Linux
   sudo apt-get install chromium-browser
   
   # macOS
   brew install --cask google-chrome
   

2. Update to the latest Chrome version

3. Try without headless mode (modify in code)

4. 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:

1. Increase timeout value:

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

2. Check your internet connection

3. Use a VPN if websites are geo-blocked

4. Some sites may be temporarily down - retry later

Too many failed profiles

Problem: Most searches return “failed” status.

Solution:

1. Websites may be blocking automated requests. Try:

   • Using a proxy
   • Reducing number of workers
   • Increasing timeout

2. Filter to only see detected profiles:

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

3. 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:

1. This is expected for some websites with anti-bot protection

2. The web app interface (not CLI) may handle CAPTCHAs better:

   npm start
   # Open http://localhost:9005/app.html
   

3. Use mode options to avoid heavy detection:

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

4. 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:

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

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

2. Check username spelling and format

3. Try variations of the username:

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

4. Verify internet connectivity

JSON output is malformed

Problem: JSON output cannot be parsed.

Solution:

1. Ensure silent mode when using JSON:

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

2. Use output redirection properly:

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

3. Check for error messages mixed in output

Docker Issues

Docker container exits immediately

Problem: Container starts then stops.

Solution:

1. Check container logs:

   docker logs <container_id>
   

2. Ensure port 9005 is not already in use:

   lsof -i :9005
   

3. 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:

1. Verify container is running:

   docker ps
   

2. Check correct URL: http://localhost:9005/app.html

3. Try http://0.0.0.0:9005/app.html or http://127.0.0.1:9005/app.html

4. Check firewall settings

Docker compose grid mode not working

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

Solution:

1. Ensure docker-compose.yml is present:

   ls -la docker-compose.yml
   

2. Check Docker Compose version:

   docker-compose --version
   

3. Rebuild containers:

   docker-compose down
   docker-compose up --build
   

Performance Issues

Search is very slow

Problem: Searches take too long to complete.

Solution:

1. Use --top to search fewer sites:

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

2. Target specific websites:

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

3. Use fast mode:

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

4. Increase worker count (requires code modification):

   SocialAnalyzer.workers = 30
   

5. Reduce timeout:

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

High memory usage

Problem: Social Analyzer consumes too much RAM.

Solution:

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

Metadata and Extraction Issues

Metadata extraction returns empty results

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

Solution:

1. Ensure profiles are detected first

2. Metadata depends on profile structure - not all sites support it

3. Use with extract flag:

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

4. 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:

1. Check permissions in temp directory

2. Specify custom log directory:

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

3. 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:

1. Check GitHub Issues: https://github.com/qeeqbox/social-analyzer/issues
2. Search for similar problems - your issue may already be solved
3. 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