Skip to content

troubleshooting.md

Latest commit

 

History

History
425 lines (314 loc) · 11.6 KB

troubleshooting.md

File metadata and controls

425 lines (314 loc) · 11.6 KB

Troubleshooting Guide

Common issues and solutions for Telegram Multi-Account Message Sender.

Installation Issues

Python Not Found

Problem: python: command not found or Python was not found

Solutions:

  1. Install Python 3.10+ from python.org
  2. Add Python to PATH during installation
  3. Verify installation: python --version
  4. On Windows, try py instead of python

Dependencies Installation Fails

Problem: pip install fails with errors

Solutions:

  1. Update pip: python -m pip install --upgrade pip
  2. Use virtual environment: 
    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
  3. Install dependencies individually to identify the problematic package
  4. Check Python version compatibility

PyQt5 Installation Issues

Problem: PyQt5 fails to install

Solutions:

  1. Install system dependencies:
    • Ubuntu/Debian: sudo apt-get install python3-pyqt5
    • macOS: brew install pyqt5
    • Windows: Usually works with pip
  2. Try: pip install --upgrade PyQt5
  3. Use pre-built wheels: pip install PyQt5 --only-binary :all:

Application Startup Issues

Application Won't Start

Problem: Application crashes on startup or doesn't launch

Solutions:

  1. Check Python version: python --version (must be 3.10+)
  2. Verify all dependencies: pip list | grep -i pyqt5
  3. Check logs in app_data/logs/ directory
  4. Run from command line to see error messages: 
    python main.py
  5. Try running with debug mode: 
    python -u main.py

GUI Not Displaying

Problem: Application runs but no window appears

Solutions:

  1. Check if window is minimized or off-screen
  2. Verify display settings and resolution
  3. Try running with environment variable: 
    QT_QPA_PLATFORM=offscreen python main.py
  4. Check for multiple displays and window positioning
  5. Restart the application

Import Errors

Problem: ModuleNotFoundError or ImportError

Solutions:

  1. Verify installation: pip install -r requirements.txt
  2. Check Python path: python -c "import sys; print(sys.path)"
  3. Reinstall the package: pip uninstall telegram-multi-account-sender && pip install telegram-multi-account-sender
  4. Check for virtual environment activation

Account Connection Issues

Cannot Connect to Telegram

Problem: Account connection fails

Solutions:

  1. Verify API credentials (API ID and API Hash)
  2. Check internet connection
  3. Verify phone number format (include country code, e.g., +1234567890)
  4. Try disconnecting and reconnecting the account
  5. Check if Telegram service is accessible in your region
  6. Verify firewall/antivirus isn't blocking the connection

Authorization Code Not Received

Problem: SMS or phone call code not received

Solutions:

  1. Check phone number is correct
  2. Wait a few minutes and try again
  3. Request phone call instead of SMS
  4. Check if phone has signal
  5. Verify phone number format includes country code
  6. Try from a different network if possible

Account Gets Disconnected

Problem: Account disconnects frequently

Solutions:

  1. Check internet connection stability
  2. Verify API credentials are still valid
  3. Check for account restrictions on Telegram
  4. Reduce number of simultaneous connections
  5. Check system resources (RAM, CPU)
  6. Review logs for specific error messages

Message Sending Issues

Messages Not Sending

Problem: Messages fail to send

Solutions:

  1. Check internet connection
  2. Verify recipient username or phone number is correct
  3. Check if account is connected: Go to Accounts tab
  4. Review rate limiting settings
  5. Check logs for specific error messages
  6. Verify account is not restricted or banned
  7. Try sending a test message manually

Rate Limit Errors

Problem: "Rate limit exceeded" or "Too many requests"

Solutions:

  1. Reduce rate limit in campaign settings
  2. Increase delay between messages
  3. Use account warmup for new accounts
  4. Spread messages across multiple accounts
  5. Wait before retrying
  6. Check Telegram's current rate limits

Invalid Recipient Errors

Problem: "User not found" or "Invalid recipient"

Solutions:

  1. Verify recipient username is correct (without @)
  2. Check if recipient has privacy settings blocking messages
  3. Verify phone number format if using phone number
  4. Ensure recipient exists and is accessible
  5. Try sending a test message first

Media Not Sending

Problem: Media files fail to attach or send

Solutions:

  1. Verify media file exists and is accessible
  2. Check file size (Telegram has size limits)
  3. Verify file format is supported (images, videos, documents)
  4. Check file permissions
  5. Try a different media file
  6. Use media URL instead of file path if supported

Campaign Issues

Campaign Won't Start

Problem: Campaign remains in "Pending" status

Solutions:

  1. Check if at least one account is connected
  2. Verify recipients are selected
  3. Check campaign settings are valid
  4. Review logs for error messages
  5. Try creating a new campaign
  6. Verify start time is not in the past

Campaign Stops Unexpectedly

Problem: Campaign stops before completion

Solutions:

  1. Check logs for error messages
  2. Verify account is still connected
  3. Check for rate limit issues
  4. Verify internet connection is stable
  5. Check system resources
  6. Review campaign settings

Campaign Performance Issues

Problem: Campaign runs very slowly

Solutions:

  1. Reduce rate limit
  2. Close other applications
  3. Check system resources (CPU, RAM)
  4. Reduce number of simultaneous campaigns
  5. Check internet connection speed
  6. Optimize recipient lists

Database Issues

Database Errors

Problem: Database-related errors

Solutions:

  1. Check database file permissions
  2. Verify disk space is available
  3. Try backing up and restoring database
  4. Check for database corruption
  5. Reinitialize database (backup first): 
    from app.services import initialize_database
initialize_database()

Data Loss

Problem: Data disappears or is lost

Solutions:

  1. Check if database file exists: app_data/app.db
  2. Restore from backup if available
  3. Check for soft-deleted records (they may be recoverable)
  4. Verify you're looking at the correct database file
  5. Check application logs for clues

Performance Issues

Application is Slow

Problem: Application runs slowly or freezes

Solutions:

  1. Close other applications
  2. Reduce number of active campaigns
  3. Lower rate limits
  4. Check system resources (Task Manager / Activity Monitor)
  5. Restart the application
  6. Check for memory leaks in logs
  7. Update to latest version

High Memory Usage

Problem: Application uses too much memory

Solutions:

  1. Reduce number of active campaigns
  2. Clear old logs
  3. Restart the application periodically
  4. Check for memory leaks
  5. Reduce number of connected accounts
  6. Close unused tabs/widgets

High CPU Usage

Problem: Application uses too much CPU

Solutions:

  1. Reduce rate limits
  2. Reduce number of simultaneous operations
  3. Check for infinite loops in logs
  4. Update to latest version
  5. Restart the application

UI/Display Issues

Interface Not Displaying Correctly

Problem: UI elements are misaligned or missing

Solutions:

  1. Try different theme
  2. Check display scaling settings
  3. Restart the application
  4. Update PyQt5: pip install --upgrade PyQt5
  5. Check for custom stylesheet issues
  6. Try resetting settings

Language Not Changing

Problem: Language setting doesn't apply

Solutions:

  1. Restart the application after changing language
  2. Verify translation files exist: app/translations/
  3. Check language code is correct (e.g., "en", "es", "fr")
  4. Clear application cache
  5. Reinstall the application

Theme Not Applying

Problem: Theme doesn't change or looks wrong

Solutions:

  1. Restart the application
  2. Try a different theme
  3. Check theme files exist
  4. Clear application cache
  5. Reset to default theme

Logging Issues

Logs Not Generated

Problem: No log files are created

Solutions:

  1. Check app_data/logs/ directory exists
  2. Verify write permissions
  3. Check disk space
  4. Review logging configuration in settings
  5. Check application logs for errors

Logs Too Large

Problem: Log files are very large

**Solutions:1. Configure log rotation in settings 2. Delete old log files manually 3. Reduce log level (INFO instead of DEBUG) 4. Use "Delete All Logs" feature 5. Set up automatic log cleanup

Network Issues

Connection Timeouts

Problem: Frequent connection timeouts

Solutions:

  1. Check internet connection stability
  2. Verify firewall settings
  3. Check proxy configuration if using proxy
  4. Try different network
  5. Increase timeout settings if available
  6. Check Telegram service status

Proxy Issues

Problem: Proxy not working

Solutions:

  1. Verify proxy settings (host, port, type)
  2. Check proxy credentials if required
  3. Test proxy connection separately
  4. Try different proxy
  5. Check if proxy supports Telegram protocol
  6. Verify proxy is not blocked

Getting Help

Still Having Issues?

If you're still experiencing problems:

  1. Check Documentation:

  2. Review Logs:

    • Check app_data/logs/ for error messages
    • Look for specific error codes or messages
    • Note when the issue occurs

  3. Gather Information:

    • Application version
    • Operating system and version
    • Python version
    • Error messages from logs
    • Steps to reproduce the issue

  4. Report the Issue:

    • Use Bug Report Template
    • Include all gathered information
    • Provide steps to reproduce
    • Attach relevant log files (remove sensitive data)

  5. Contact Support:

Prevention Tips

Best Practices

  1. Regular Backups: Backup your database regularly
  2. Monitor Logs: Check logs periodically for warnings
  3. Update Regularly: Keep the application updated
  4. Test First: Always test messages before large campaigns
  5. Rate Limits: Use conservative rate limits
  6. Account Warmup: Warm up new accounts gradually
  7. System Maintenance: Keep your system updated and optimized

Common Mistakes to Avoid

  1. Too High Rate Limits: Can lead to account bans
  2. Not Testing: Always test before sending to many recipients
  3. Ignoring Errors: Address errors promptly
  4. No Backups: Always backup important data
  5. Using Banned Accounts: Check account status regularly
  6. Invalid Recipients: Verify recipients before campaigns

See Also