Skip to content

Troubleshooting

This page helps you resolve common issues with the MSM Data Collector Client.

Application Won't Start

Python Not Found

Symptom: Error message "python is not recognized as a command"

Solution:

  1. Verify Python is installed: Open terminal and run python --version
  2. If not installed, see Installation Guide
  3. On Windows, ensure "Add Python to PATH" was checked during installation
  4. Try using python3 instead of python (macOS/Linux)

Missing Dependencies

Symptom: Import errors or module not found errors

Solution:

pip install -r requirements.txt

If that fails, try:

pip install --user -r requirements.txt

Tkinter Not Available

Symptom: "tkinter module not found" error

Solution:

  • Windows/Mac: Tkinter should come with Python. Reinstall Python if missing.
  • Linux: Install tkinter package: 
    sudo apt-get install python3-tk

Connection Issues

Can't Connect to MSM Server

Symptom: SSH connection failed or timeout errors

Solution:

  1. Verify MSM server is online and accessible
  2. Check config.yaml has correct host, port, username, and password
  3. Test SSH connection manually: 
    ssh username@msm-server-hostname
  4. Verify firewall allows SSH connections (port 22)
  5. Contact your network administrator if issues persist

Database Connection Failed

Symptom: PostgreSQL connection errors

Solution:

  1. Verify SSH tunnel to MSM server is working
  2. Check config.yaml database credentials are correct
  3. Verify database is running on the MSM server
  4. Check database name, username, and password
  5. Contact your database administrator

Upload Failures

Symptom: Can't upload to cloud platform

Solution:

  1. Check your internet connection
  2. Verify api.base_url in config.yaml is correct
  3. Test API accessibility: 
    ping data-collector.aws.ayk-services.com
  4. Check with administrator about cloud platform status
  5. Try Offline Mode then upload later

Performance Issues

Extraction is Very Slow

Symptom: Data extraction takes much longer than expected

Solutions:

  1. Reduce batch size to 500 or 250
  2. Check your network connection speed
  3. Verify MSM server is not under heavy load
  4. Use Offline Mode for better performance
  5. Extract data in smaller date ranges

Application Uses Too Much Memory

Symptom: Computer becomes slow or unresponsive

Solutions:

  1. Reduce batch size in extraction settings
  2. Close other applications
  3. Extract data in smaller date ranges
  4. Restart the application between large extractions

Slow Upload Speed

Symptom: File uploads take very long

Solutions:

  1. Check internet connection speed
  2. Upload during off-peak hours
  3. Use wired connection instead of WiFi
  4. Close bandwidth-heavy applications
  5. Upload smaller files or split large extractions

Data Issues

No Data Extracted

Symptom: Extraction completes but zero records

Solutions:

  1. Verify date range has data in the database
  2. Check table_name in config.yaml is correct
  3. Verify timestamp_column matches database schema
  4. Check database permissions for your user account
  5. Review logs at logs/extraction.log

Duplicate Data

Symptom: Same data uploaded multiple times

Solutions:

  1. Don't restart extractions from the same start date
  2. Track last successful extraction timestamp
  3. Use that timestamp as start date for next extraction
  4. Check logs to find last processed record
  5. Contact administrator to remove duplicates from cloud

Missing Data

Symptom: Some records not extracted

Solutions:

  1. Check logs for error messages during extraction
  2. Verify date range covers intended period
  3. Check for interruptions during extraction
  4. Re-run extraction for missing date ranges
  5. Verify database had data for that period

Configuration Issues

Invalid Configuration File

Symptom: Error loading config.yaml

Solutions:

  1. Verify YAML syntax is correct (use a YAML validator)
  2. Check indentation (use spaces, not tabs)
  3. Ensure all required fields are present
  4. Remove any special characters from passwords
  5. Compare with the configuration template

Authentication Failed

Symptom: Invalid credentials errors

Solutions:

  1. Double-check username and password in config.yaml
  2. Verify there are no extra spaces before/after credentials
  3. Check if password contains special characters that need escaping
  4. Confirm account is active with your administrator
  5. Test credentials manually via SSH

File and Storage Issues

Can't Create Output Files

Symptom: Permission denied errors when saving files

Solutions:

  1. Check you have write permissions to the application folder
  2. Create offline_extractions/ folder manually if missing
  3. Run application with appropriate permissions
  4. Choose a different output directory with write access

Disk Space Full

Symptom: Not enough space errors

Solutions:

  1. Free up disk space
  2. Delete old extraction files after successful upload
  3. Extract smaller date ranges
  4. Use different drive with more space
  5. Clean up log files in logs/ folder

Can't Delete Files

Symptom: Permission errors when deleting files

Solutions:

  1. Close the application first
  2. Ensure no other program has files open
  3. Check file permissions
  4. Delete files manually from file explorer

Interface Issues

Application Window Not Appearing

Symptom: Command runs but no window appears

Solutions:

  1. Check terminal for error messages
  2. Verify tkinter is installed: python -c "import tkinter"
  3. Check if window appeared behind other windows
  4. Try running with elevated permissions
  5. Check display settings (especially on Linux with remote sessions)

Interface Frozen

Symptom: Window doesn't respond to clicks

Solutions:

  1. Check terminal for errors
  2. Wait - large operations take time
  3. Close and restart the application
  4. Check logs at logs/extraction.log

Progress Not Updating

Symptom: Progress bar stuck or not moving

Solutions:

  1. Wait - large batches take time
  2. Check terminal for error messages
  3. Check logs at logs/extraction.log
  4. Restart extraction if genuinely stuck

Error Messages

"Connection refused"

Cause: Can't reach the server

Solution: Check network connection, firewall settings, and server address

"Authentication failed"

Cause: Invalid credentials

Solution: Verify username and password in config.yaml

"Permission denied"

Cause: Insufficient file system or database permissions

Solution: Check file permissions or contact administrator for database access

"Timeout error"

Cause: Operation took too long

Solution: Reduce batch size, check network connection, or split into smaller extractions

"File not found"

Cause: Missing required file

Solution: Verify file path, check file exists, or recreate from template

Getting Additional Help

If you can't resolve your issue:

Check the Logs

Detailed logs are in: 

logs/extraction.log

Look for ERROR or WARNING messages.

Information to Provide

When contacting support, include:

  • Error message (exact text)
  • What you were doing when error occurred
  • Relevant log entries from logs/extraction.log
  • Your Python version: python --version
  • Operating system and version
  • Screenshot of the error (if applicable)

Contact Support

  • Technical Issues: Contact your system administrator
  • Data Questions: Contact your data team
  • Access Issues: Contact your IT support team

Frequently Asked Questions

See the FAQ page for common questions about usage and features.