# RateLoader v3.0 - Troubleshooting Guide

This guide provides solutions to common issues and problems that may occur while using RateLoader v3.0.

## Table of Contents

1. [Installation Issues](#installation-issues)
2. [Database Connection Problems](#database-connection-problems)
3. [Email Configuration Issues](#email-configuration-issues)
4. [HTTP Server Problems](#http-server-problems)
5. [Task Execution Issues](#task-execution-issues)
6. [Scheduler Problems](#scheduler-problems)
7. [Performance Issues](#performance-issues)
8. [GUI Issues](#gui-issues)
9. [Logging and Debugging](#logging-and-debugging)
10. [File and Directory Issues](#file-and-directory-issues)

## Installation Issues

### Python Version Compatibility

**Problem**: Application fails to start with import errors or compatibility issues.

**Solution**:

- Ensure you're using Python 3.8 (32-bit) for Oracle compatibility
- Check Python version: `python --version`
- Verify architecture: `python -c "import platform; print(platform.architecture())"`
- Install 32-bit Python if necessary

**Required Dependencies**:

```bash
pip install cx_Oracle==7.3 requests python-dateutil
```

### Oracle Client Installation

**Problem**: `cx_Oracle` import fails or database connection errors.

**Solution**:

1. Download Oracle Instant Client (32-bit) from Oracle website
2. Extract to a directory (e.g., `C:\oracle\instantclient_19_9`)
3. Add to PATH: `set PATH=%PATH%;C:\oracle\instantclient_19_9`
4. Set ORACLE_HOME: `set ORACLE_HOME=C:\oracle\instantclient_19_9`

### Missing DLL Files

**Problem**: Application fails with DLL import errors.

**Solution**:

- Install Visual C++ Redistributable for Visual Studio 2015-2019
- Ensure Oracle client DLLs are in PATH
- Restart application after PATH changes

## Database Connection Problems

### Connection String Issues

**Problem**: "ORA-12154: TNS:could not resolve the connect identifier" or similar errors.

**Solution**:

1. Verify connection string format in `settings.ini`:
   ```ini
   oracleconnectstring = username/password@dsn
   ```
2. Test with SQL\*Plus or other Oracle tools
3. Check TNS names configuration in `tnsnames.ora`
4. Try using full connection descriptor:
   ```ini
   oracleconnectstring = username/password@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=servicename)))
   ```

### NLS_LANG Configuration

**Problem**: Character encoding issues or Oracle connection failures.

**Solution**:

1. Verify NLS_LANG setting in `settings.ini`:
   ```ini
   nls_lang = AMERICAN_AMERICA.CL8MSWIN1251
   ```
2. Common NLS_LANG values:
   - `AMERICAN_AMERICA.CL8MSWIN1251` - Cyrillic support
   - `AMERICAN_AMERICA.WE8MSWIN1252` - Western European
   - `AMERICAN_AMERICA.AL32UTF8` - Unicode

### Network Connectivity

**Problem**: Connection timeouts or network-related errors.

**Solution**:

1. Test network connectivity: `tnsping hostname`
2. Check firewall settings on database server
3. Verify VPN requirements if applicable
4. Test with simple connection script:
   ```python
   import cx_Oracle
   conn = cx_Oracle.connect('user/pass@host:port/service')
   print("Connection successful")
   ```

## Email Configuration Issues

### SMTP Authentication

**Problem**: "SMTP Authentication failed" or similar errors.

**Solution**:

1. Verify email settings in `settings.ini`:
   ```ini
   sendfrom = your-email@example.com
   sendto = recipient@example.com
   mailserver = smtp.example.com
   port = 587
   pwd = your-password
   ssl = 1
   ```
2. Test with email client using same settings
3. Check for app-specific passwords if using Gmail/Outlook
4. Verify SSL/TLS requirements with email provider

### SSL/TLS Configuration

**Problem**: Email sending fails with SSL/TLS errors.

**Solution**:

1. Try different SSL settings:
   ```ini
   ssl = 0  # No SSL
   ssl = 1  # SSL/TLS
   ```
2. Test different ports:
   - Port 25: No SSL
   - Port 587: STARTTLS
   - Port 465: SSL/TLS

### Attachment Issues

**Problem**: Emails sent without attachments or attachment errors.

**Solution**:

1. Verify CSV files are created successfully
2. Check file permissions on CSV files
3. Ensure attachment files exist when email is sent
4. Check file size limits with email provider

## HTTP Server Problems

### Port Conflicts

**Problem**: "Address already in use" error when starting HTTP server.

**Solution**:

1. Find process using the port:
   ```cmd
   netstat -ano | findstr :8000
   ```
2. Kill conflicting process or change port in `settings.ini`:
   ```ini
   server_port = 8001
   ```
3. Restart application

### Firewall Issues

**Problem**: External clients cannot connect to HTTP server.

**Solution**:

1. Add Windows Firewall rule for the application
2. Check antivirus/firewall software
3. Test local connection: `curl http://localhost:8000/ping`
4. Verify server is listening: `netstat -an | findstr :8000`

### Request Handling

**Problem**: HTTP requests fail or return unexpected responses.

**Solution**:

1. Check server status: `curl http://localhost:8000/status`
2. Verify JSON format for POST requests
3. Check log files for error details
4. Test with simple curl command:
   ```bash
   curl -X POST -H "Content-Type: application/json" -d '{"prices":[]}' http://localhost:8000/load
   ```

## Task Execution Issues

### Task Queue Problems

**Problem**: Tasks are not executing or queue is stuck.

**Solution**:

1. Check task queue status via GUI or API
2. Restart application to reset queue
3. Check log files for error messages
4. Verify worker thread is running

### Oracle Query Failures

**Problem**: Export tasks fail with Oracle errors.

**Solution**:

1. Check SQL file downloads: verify URLs are accessible
2. Test SQL queries manually in Oracle client
3. Check Oracle connection stability
4. Verify query permissions for database user

### File Permission Issues

**Problem**: CSV files cannot be created or written.

**Solution**:

1. Check write permissions in application directory
2. Ensure no other process has files locked
3. Run application as administrator if necessary
4. Check disk space availability

## Scheduler Problems

### Scheduled Tasks Not Running

**Problem**: Tasks don't execute at scheduled times.

**Solution**:

1. Verify schedule hours in `settings.ini`:
   ```ini
   schedule_hours = 8,12,15,18,20
   ```
2. Check system time and timezone
3. Ensure scheduler is running (check GUI status)
4. Manually trigger tasks to test functionality

### Time Zone Issues

**Problem**: Tasks run at wrong times.

**Solution**:

1. Verify system time zone settings
2. Check Windows time synchronization
3. Adjust schedule hours for local time zone
4. Use 24-hour format in configuration

## Performance Issues

### Memory Usage

**Problem**: Application uses excessive memory over time.

**Solution**:

1. Monitor memory usage in Task Manager
2. Restart application periodically
3. Check log file sizes (should rotate automatically)
4. Verify Oracle connections are properly closed

### Slow Performance

**Problem**: Application responds slowly or tasks take too long.

**Solution**:

1. Check database performance for slow queries
2. Optimize SQL queries if possible
3. Check network latency to database
4. Monitor system resources (CPU, disk I/O)

### Database Connection Pooling

**Problem**: Too many database connections or connection exhaustion.

**Solution**:

1. Verify connections are properly closed
2. Check for connection leaks in error scenarios
3. Monitor database connection count
4. Implement connection pooling if needed

## GUI Issues

### GUI Not Starting

**Problem**: GUI fails to start or shows errors.

**Solution**:

1. Ensure tkinter is installed (comes with Python)
2. Check Python installation: `python -m tkinter`
3. Run in background mode: `python main.py`
4. Check for missing DLL files

### GUI Freezing

**Problem**: GUI becomes unresponsive during operations.

**Solution**:

1. Operations should run in background threads
2. Check for long-running operations in main thread
3. Verify task queue is functioning properly
4. Restart GUI if frozen

### Status Not Updating

**Problem**: GUI status displays stale information.

**Solution**:

1. Check auto-refresh is enabled in Logs tab
2. Verify backend components are running
3. Check network connectivity for status updates
4. Restart GUI to refresh connections

## Logging and Debugging

### Log File Issues

**Problem**: Log files not created or not updating.

**Solution**:

1. Verify `log/` directory exists and is writable
2. Check file permissions
3. Ensure disk space is available
4. Restart application to reinitialize logging

### Debug Mode

**Problem**: Need more detailed logging for troubleshooting.

**Solution**:

1. Check unified log file in `log/` directory:
   - `rateloader.log` - All operations with component prefixes
2. Look for ERROR level messages and component prefixes:
   - `[EXPORT]` - CSV/email export operations
   - `[PRICE]` - API export operations
   - `[RATELOADER]` - Core application operations
   - `[GUI]` - GUI interface operations
   - `[ORACLE]` - Database operations
   - `[SCHEDULER]` - Task scheduling operations
   - `[HTTP]` - HTTP server operations
   - `[QUEUE]` - Task queue operations
3. Filter log by component using text search
4. Enable debug logging if needed (modify code)

### Error Analysis

**Problem**: Need to analyze complex error scenarios.

**Solution**:

1. Check the unified log file for component-specific error patterns
2. Look for exception stack traces with component prefixes
3. Check for resource exhaustion messages across components
4. Review configuration changes before errors
5. Use text filtering to focus on specific components

## File and Directory Issues

### Settings.ini Problems

**Problem**: Configuration not loading or corrupted.

**Solution**:

1. Backup current `settings.ini`
2. Delete file and restart to recreate defaults
3. Manually edit with correct syntax
4. Verify INI format: sections in brackets, key=value pairs

### SQL File Download Issues

**Problem**: SQL files not downloading from URLs.

**Solution**:

1. Test URL accessibility in browser
2. Check network connectivity and proxy settings
3. Verify firewall allows HTTP/HTTPS
4. Check for authentication requirements

### CSV File Issues

**Problem**: CSV files not created or have wrong format.

**Solution**:

1. Check file encoding settings in `settings.ini`
2. Verify Oracle query returns expected data
3. Check file permissions in output directory
4. Validate CSV format with text editor

## Advanced Troubleshooting

### Component Isolation

**Problem**: Need to isolate which component is causing issues.

**Solution**:

1. Test components individually:
   - Database: `python test_oracle.py`
   - Export: `python test_export_mailer.py`
   - API: `python test_price_export.py`
   - Full integration: `python test_full_integration.py`
2. Run specific test suites to isolate problems
3. Check individual component logs

### Network Diagnostics

**Problem**: Network connectivity issues affecting multiple components.

**Solution**:

1. Test basic connectivity: `ping hostname`
2. Test specific ports: `telnet hostname port`
3. Check DNS resolution: `nslookup hostname`
4. Verify proxy settings if applicable

### Oracle Diagnostics

**Problem**: Complex Oracle-related issues.

**Solution**:

1. Test with Oracle SQL Developer or similar tool
2. Check Oracle listener status: `lsnrctl status`
3. Verify database is running: `sqlplus / as sysdba`
4. Check Oracle alert logs for database issues

## Getting Help

### Before Contacting Support

1. Gather information:
   - Error messages from log files
   - Steps to reproduce the issue
   - System information (OS, Python version)
   - Configuration files (remove sensitive data)

### Diagnostic Information Collection

Create a support package with:

1. Unified log file `rateloader.log` from `log/` directory
2. `settings.ini` (remove passwords)
3. System information: `systeminfo`
4. Python environment: `pip freeze`

### Common Debug Commands

```bash
# Check Python version and architecture
python --version
python -c "import platform; print(platform.architecture())"

# Test Oracle connection
python -c "import cx_Oracle; print('cx_Oracle version:', cx_Oracle.version)"

# Test network connectivity
ping your-database-server
telnet your-database-server 1521

# Check running processes
tasklist | findstr python
netstat -ano | findstr :8000
```

## Recovery Procedures

### Application Recovery

1. Stop all running instances
2. Backup configuration and log files
3. Delete corrupted files if necessary
4. Restart with clean configuration
5. Reconfigure settings from backup

### Database Recovery

1. Verify database is accessible
2. Check connection string and credentials
3. Test with simple query
4. Restart application after database recovery

### Data Recovery

1. Check for partial CSV files
2. Verify email delivery status
3. Check API export logs for successful transmissions
4. Manually re-run failed operations if needed

---

For additional support or questions not covered in this guide, please contact the support team with detailed error information and diagnostic data.
