🔧 Troubleshooting

📧 Email Issues

Problem: "Cannot send invoice via Gmail"

Causes: Using regular password instead of App Password, 2-factor authentication not enabled, or "Less secure apps" not allowed.

Solutions:

1. Generate a Gmail App Password:
   • Go to myaccount.google.com/apppasswords
   • Select "Mail" and "Windows Computer"
   • Generate password (16-character code)
   • Use this code in FreelanceTimer.pro — not your regular Gmail password
2. Enable 2-Factor Authentication:
   • App Passwords require 2FA to be enabled
   • Go to Google Account → Security → Enable 2-Step Verification
3. Check SMTP Settings:
   • Server: smtp.gmail.com
   • Port: 587
   • Encryption: TLS
4. Test Connection: Settings → Email → Click "Test Connection" — check the error message if it fails

Problem: "Email sent but client didn't receive it"

1. Check Spam/Junk Folder: Ask client to check spam and add you to their contacts
2. Verify Email Address: Double-check the client email in the Clients tab for typos
3. Check Sent Folder: Open Gmail in browser and confirm the email appears in Sent
4. PDF Attachment Size: Large invoices may be blocked — check file size (should be under 10MB)

💾 Database Issues

Problem: "Database file not found"

Causes: Database moved or deleted, cloud sync folder not connected, or path changed.

Solutions:

1. Verify Database Location:
   • Settings → Database → Check path
   • Navigate to that folder in File Explorer
   • Confirm time_tracker.db exists
2. If Using Cloud Storage:
   • Ensure Google Drive/OneDrive is synced
   • Check for sync errors in the cloud app
   • Wait for sync to complete before opening
3. Restore from Backup: Locate your backup file, copy to original location, restart FreelanceTimer.pro
4. Create New Database: Settings → Database → "Create New Database" → Choose location

Problem: "Database locked" or "Cannot write to database"

Causes: Multiple instances of app running, cloud sync conflict, or file permissions issue.

Solutions:

1. Close Extra Instances: Task Manager → Find "FreelanceTimer.pro" → End all instances → Restart app
2. Check File Permissions:
   • Right-click time_tracker.db → Properties → Security
   • Ensure your user account has "Full Control"
3. Pause Cloud Sync: Temporarily pause Google Drive/OneDrive sync, save changes in app, then resume sync

⏱️ Timer Issues

Problem: Timer won't start

1. Verify Selections: Ensure Client, Project, and Task are all selected
2. Check for Running Timer: Only one timer can run at a time — stop any active timers first
3. Restart App: Close and reopen FreelanceTimer.pro

Problem: Timer shows incorrect time

Causes: Computer clock is wrong or time zone mismatch.

Solutions:

1. Check System Clock: Right-click taskbar clock → Adjust date/time → Enable "Set time automatically"
2. Verify Time Zone: Settings → Time & Language → Time Zone → Ensure correct zone is selected

Problem: Timer entry not saving

1. Confirm All Required Fields: Client, Project, and Task must all be selected — check for validation errors
2. Check Database Connection: Settings → Database → Verify path
3. Review Time Entries Tab: Entry may have saved but not appeared due to filters — clear date range filters and expand client/project trees

📄 Invoice Issues

Problem: "No time entries found for invoice"

Causes: All entries already billed, date range doesn't include entries, or filters excluding data.

Solutions:

1. Expand Date Range: Invoice tab → Date picker → Select wider range (e.g., "Last 90 days")
2. Check "Include Billed": Invoice tab → Settings → Enable "Include already-billed entries"
3. Verify Time Entries Exist: Time Entries tab → Confirm entries match selected client/project

Problem: Invoice totals are incorrect

1. Verify Hourly Rates: Projects tab → Check project rates; Tasks tab → Check task rate overrides
2. Check Time Entry Calculations: Time Entries tab → Review individual entries and recalculate totals manually
3. Review Rounding Settings: Settings → Invoices → Check rounding rules

Problem: PDF won't generate

Causes: Missing ReportLab library, file permissions, or invalid characters in data.

Solutions:

1. Reinstall Dependencies: Open Command Prompt as Administrator → Run: pip install reportlab
2. Check Save Location: Choose a folder you have write access to — avoid special characters in filename
3. Review Invoice Data: Remove special characters from client/project names and check for very long descriptions

🖥️ Application Issues

Problem: App won't launch

1. Check System Requirements: Windows 10 or 11 required, 50MB free disk space
2. Run as Administrator: Right-click app → "Run as administrator"
3. Reinstall: Uninstall FreelanceTimer.pro, download a fresh installer, reinstall — your database is safe if stored separately
4. Check for Conflicting Software: Antivirus may be blocking — add an exception for FreelanceTimer.pro

Problem: App crashes frequently

1. Update to Latest Version: Help → Check for Updates
2. Check Database Integrity: Backup database first → Settings → Database → "Repair Database" (if available)
3. Clear App Cache: Settings → Advanced → "Clear Cache"
4. Report Bug: GitHub Issues — include the error message and steps to reproduce

Problem: Interface looks wrong (fonts, colors, layout)

Causes: High DPI scaling or theme issues.

Solutions:

1. Adjust DPI Settings: Right-click app shortcut → Properties → Compatibility → "Override high DPI scaling behavior"
2. Change Theme: Settings → Appearance → Select different theme
3. Reset to Defaults: Settings → Advanced → "Reset UI Settings"

📊 Export Issues

Problem: Excel export fails

1. Check File Location: Ensure you have write permission — try choosing a different folder
2. Close Excel: Close any open Excel files with the same name, then try again
3. Check Data Format: Ensure no corrupted time entries — try exporting a smaller date range

🔄 Sync Issues (Cloud Storage)

Problem: Changes not syncing between computers

1. Verify Cloud Sync: Check Google Drive/OneDrive sync status and look for sync errors
2. Close App Before Switching: Always close the app on Computer A, wait for cloud sync to complete, then open on Computer B
3. Avoid Simultaneous Use: Don't open the app on multiple computers at once — database conflicts may occur
4. Manual Sync: Close app → manually trigger cloud sync → wait for completion → open on other device

🆘 Still Having Issues?

1. Check Full Documentation: freelancetimer.pro/docs
2. Search GitHub Issues: Someone may have already reported the same problem — search here
3. Report a Bug: GitHub Issues — include your Windows version, app version (Help → About), exact error message, and steps to reproduce
4. Contact Support: support@freelancetimer.pro
   • Response time: 48 hours (Pro users), 5–7 days (Free users)
   • Include: your email, app version, detailed description, and screenshots if applicable