Common Issues

Troubleshoot common problems with the AI Photo Trainer desktop application. Follow these step-by-step solutions to resolve issues quickly and get back to rating photos.

Application Won't Start

Symptoms

Double-click desktop icon, nothing happens. Application doesn't launch or window doesn't appear.

Solutions

1. Check Task Manager (Press Ctrl+Shift+Esc)
   • Look for "AI Photo Training" in the Processes tab
   • If found, the app is running but window may be hidden
   • Right-click the process → End task
   • Try launching the application again
2. Restart Your Computer
   • Sometimes a clean reboot resolves startup conflicts
   • Save any open work first
3. Run as Administrator
   • Right-click desktop shortcut
   • Select "Run as administrator"
   • Click "Yes" if prompted for permissions
   • Some system configurations require elevated privileges
4. Check Log Files
   • Navigate to: C:\Users\[YourUsername]\AppData\Local\AI Photo Training\logs\
   • Open the most recent log file (sorted by date)
   • Look for error messages or stack traces
   • Search for keywords like "ERROR", "FATAL", "EXCEPTION"
5. Reinstall Application
   • Uninstall via Windows Settings → Apps
   • Download fresh installer
   • Run new installation
   • Your data in AppData\Local will be preserved

Backend Connection Failed

Symptoms

Application launches but displays error: "Unable to connect to backend server" or "Backend not responding".

Solutions

1. Wait 30 Seconds
   • Backend server may still be starting up
   • First launch can take longer (15-30 seconds)
   • Watch for backend initialization messages
2. Check Task Manager
   • Press Ctrl+Shift+Esc
   • Look for "ai-photo-backend.exe" process
   • If missing, backend failed to start
   • Restart the application completely
3. Check Windows Firewall
   • Open Windows Defender Firewall settings
   • Click "Allow an app or feature through Windows Defender Firewall"
   • Ensure "AI Photo Training" is checked for both Private and Public networks
   • If not listed, click "Change settings" → "Allow another app" → Browse to AI Photo Training.exe
4. Check Antivirus Software
   • Some antivirus programs block the backend executable
   • Add exception for: C:\Program Files\AI Photo Training Team\AI Photo Training\
   • Temporarily disable antivirus and test (not recommended long-term)
5. Check for Port Conflicts
   • Review log files for "port in use" or "address already in use" errors
   • Backend uses port 5000 by default
   • Close other applications that might use port 5000

Models Won't Download

Symptoms

AI model download fails, freezes, or shows error during first-time setup or model update.

Solutions

1. Check Internet Connection
   • Verify you're connected to the internet
   • Test by opening a web browser
   • Download requires stable connection for 5-10 minutes
2. Sign Out and Re-authenticate
   • Settings → Model Manager → Sign out from Google
   • Restart download process
   • Sign in with Google account again
   • Grant file access permissions
3. Try Different Network
   • Corporate firewalls may block Google Drive
   • Try mobile hotspot or home network
   • Avoid public WiFi with restricted access
4. Manual Download
   • Contact support for direct model download links
   • Download files manually to your computer
   • Place model files in: C:\Users\[You]\AppData\Local\AI Photo Training\models\
   • Restart application to detect models
5. Check Available Disk Space
   • Models require approximately 2 GB of free space
   • Check C: drive free space in File Explorer
   • Clear temporary files if needed

Hot Folder Not Monitoring

Symptoms

New photos added to hot folder are not automatically rated. No notifications appear when files are added.

Solutions

1. Verify Hot Folder Settings
   • Navigate to Settings → Hot Folders
   • Verify folder path is correct
   • Check "Active" toggle is ON (green indicator)
   • Ensure folder path hasn't changed
2. Check Folder Still Exists
   • Is external drive connected?
   • Is network path still accessible?
   • Open File Explorer and navigate to folder path
   • If folder doesn't exist, hot folder monitoring pauses
3. Check File Permissions
   • Can you manually copy files to the folder?
   • Do you have read/write permissions?
   • Right-click folder → Properties → Security tab
   • Ensure your user account has full control
4. Restart Monitoring
   • Settings → Hot Folders
   • Toggle "Active" OFF
   • Wait 5 seconds
   • Toggle "Active" ON
   • Test by adding a photo
5. Remove and Re-add Hot Folder
   • Settings → Hot Folders
   • Click folder → Remove
   • Click "Add Hot Folder"
   • Browse to same folder path
   • Save and test

Hot Folder Re-Processing Old Images

Symptoms (Pre-v0.10.0)

Hot folder re-processes images from previous sessions when they are touched or modified, incorrectly associating old images with new sessions.

Solution

How v0.10.0 Fixes This:

• When you start a photographer session, the app sets a session_start_time timestamp
• Hot folder checks each file's creation time before processing
• Files created before session start are skipped and logged
• Only files created after session start are processed
• Old images remain in folder (non-destructive) but are safely ignored

Workaround for v0.9.0 and Earlier:

1. Clear hot folder before starting each new session
2. Move old images to a different folder
3. Or upgrade to v0.10.0 for automatic session-aware filtering

Images Not Appearing

Symptoms

Rated image doesn't show in the Images grid view. Photo was analyzed but isn't visible in the list.

Solutions

1. Refresh Images View
   • Press F5 or click the refresh button
   • Sometimes the UI needs a manual refresh
2. Check Filters and Search
   • Clear the search box at the top
   • Reset any active quality filters
   • Photo may be hidden by filter criteria
3. Check Database
   • Navigate to Statistics view
   • Does total photo count show the newly rated image?
   • If yes: Display issue (try refresh)
   • If no: Rating didn't save to database
4. Check Log Files
   • Review logs for database errors
   • Look for SQL errors or write failures
   • Check disk space (database needs space to grow)
5. Try Rating Another Image
   • Test with a different photo
   • If new photo appears, previous one had a save error
   • Re-rate the original photo

Slow Performance

Symptoms

Photo analysis takes longer than 30 seconds per photo. Application feels sluggish or unresponsive.

Solutions

1. Check System Resources
   • Open Task Manager (Ctrl+Shift+Esc)
   • Click Performance tab
   • Check CPU usage - should be 50-80% during analysis
   • Check RAM usage - 4GB+ recommended
2. Close Other Applications
   • Close web browsers with many tabs
   • Close video editing software or other heavy apps
   • Background processes steal CPU/RAM
3. Check GPU Usage
   • Do you have a CUDA-compatible NVIDIA GPU?
   • Are GPU drivers up to date?
   • Task Manager → Performance → GPU tab
   • If GPU isn't being used, analysis falls back to CPU (slower)
4. Reduce Photo Resolution
   • AI processes photos at maximum 1024x1024 pixels
   • Downscale very large images before rating
   • 10+ megapixel photos take longer to load
5. Check Disk Space
   • Ensure 1GB+ free space on C: drive
   • Low disk space slows all operations
   • Database and log files grow over time
6. SSD vs. HDD
   • Application runs much faster on SSD storage
   • If installed on HDD, consider moving to SSD
   • Database queries are significantly faster on SSD

Database Errors

Symptoms

Error messages containing "Database error", "SQL error", or "Cannot write to database" appear when rating photos or viewing statistics.

Solutions

1. Check Database File
   • Navigate to: C:\Users\[You]\AppData\Local\AI Photo Training\data\photo_rater.db
   • Verify file exists and isn't corrupted
   • Check file size (should be growing over time)
2. Backup Database
   • Copy photo_rater.db to a safe location
   • Desktop or Documents folder recommended
   • Always backup before troubleshooting
3. Check Disk Space
   • Database needs room to grow
   • Ensure several hundred MB free on C: drive
   • Database grows ~1MB per 100 photos
4. Check File Permissions
   • Can you create files in AppData\Local\?
   • Try creating a test text file in the folder
   • Some antivirus software blocks writes to AppData
5. Last Resort: Reset Database
   • Close AI Photo Training application completely
   • Delete photo_rater.db (after backing up!)
   • Restart application
   • App creates fresh, empty database
   • Warning: You'll lose all existing ratings
   • To restore: Replace new database with backup copy

Settings Not Syncing

Symptoms

Settings page shows "Local Settings" instead of your company name. Threshold changes made by your administrator aren't appearing on your desktop app.

Solutions

1. Check Internet Connection
   • Settings sync requires internet access during PIN login
   • Test by opening a web browser
   • If offline, cached settings from previous sync will be used
2. Log Out and Log Back In with PIN
   • Settings only sync when you enter your PIN
   • Click your name/photo in the header → Log Out
   • Enter your PIN to log back in
   • Settings should sync during login
3. Verify Rails API is Running
   • Check that the training server is accessible
   • Look for sync confirmation in desktop app logs
   • Log location: C:\Users\[You]\AppData\Local\AI Photo Training\logs\
4. Check Log Files for Sync Status
   • Look for: Synced company settings from Rails API
   • Successful sync shows company name and threshold counts
   • Errors indicate API connection or authentication issues
5. Confirm You're Associated with a Company
   • Your photographer account must be linked to a company
   • Contact your administrator to verify your account setup
   • Photographers without a company use local settings only

Local Edits Being Overwritten

This is expected behavior. When settings are synced from your company, local changes you make are intentionally overwritten on your next PIN login. This ensures all photographers use consistent quality standards.

If you need different settings:

• Request your administrator to update company-wide thresholds
• Use offline mode (don't log in with PIN) to keep local settings
• Note: Offline mode means no session tracking or badge syncing

Badges Not Unlocking

Symptoms

You've met the criteria for a badge but it remains locked. Badge progress bar shows 100% but badge isn't awarded.

Solutions

1. Verify Session is Active
   • Must be logged in with your photographer PIN
   • Session must be started (not "Skip" login)
   • Badges only unlock during active sessions
   • Check top of screen for session info bar
2. Check Badge Criteria
   • Navigate to Badges page
   • Click the locked badge
   • Verify exact requirements
   • Check progress bar percentage
3. Understand Session-Specific Badges
   • Some badges require achievements in a single session
   • Quick Draw: 100 photos in ONE 30-minute session (not cumulative)
   • Lightning Fast: 10 photos/min sustained for 5 minutes IN ONE SESSION
   • Career badges (Volume, Quality Expert) are cumulative across all sessions
4. End and Restart Session
   • Sometimes badge engine needs session refresh
   • End current session
   • Start new session with PIN
   • Rate one more photo to trigger badge check
5. Check Log Files
   • Review logs for badge engine errors
   • Search for "badge" or "achievement" keywords
   • Look for calculation errors or API failures

Duplicate Badge Entries (Pre-v0.10.0)

Symptoms (Pre-v0.10.0)

Weekly Warrior and Speed Demon badges appear as duplicates in different badge tables. Photographer has the same badge listed as both a stackable badge and a quality badge.

Root Cause

In versions prior to v0.10.0, the badge classification system incorrectly treated Weekly Warrior and Speed Demon as both stackable badges AND quality badges, causing duplicate entries in the database.

Solution

What v0.10.0 Changes:

• Weekly Warrior: Now ONLY created in photographer_quality_badges table (tiered: Bronze/Silver/Gold)
• Speed Demon: Now ONLY created in photographer_quality_badges table (tiered: Bronze/Silver/Gold)
• Removed from photographer_badge_counts (stackable badges)
• New badges created correctly in single table only

Existing Duplicate Badges:

• Duplicate badges created before v0.10.0 will remain in the database
• Does not affect new badge calculations
• Manual cleanup can be performed via Rails console if desired
• Duplicates are cosmetic only and won't cause functional issues

---

Still Need Help?

If none of these solutions resolve your issue:

• Check the FAQ for additional answers
• Review Installation and First-Time Setup guides
• Contact support at: support@aiphototraining.com
• Include log files, screenshots, and detailed steps to reproduce the issue