Troubleshooting

Common issues and their solutions.

Engine Issues

Engine Not Found

• Error: "Engine not found" or "Could not start Stockfish"
• Symptoms: Analysis button does nothing, or error message appears.
• Fix:
  1. Ensure the path in Settings > Chess Engine points to the actual stockfish.exe (Windows) or stockfish (Mac/Linux) binary, not the folder containing it.
  2. Verify the file exists at the specified path.
  3. Try re-downloading Stockfish from stockfishchess.org.
  4. On Mac/Linux, ensure the binary has execute permissions: chmod +x stockfish.

Analysis Stuck / Infinite Loading

• Issue: Analysis progress bar doesn't move or takes forever.
• Fix:
  1. Restart the application.
  2. Check if another process is using Stockfish (only one instance can run).
  3. Verify Stockfish works independently by running it from command line.
  4. Try clearing the analysis cache: Settings > Clear Cache.
  5. If issue persists, re-download the Stockfish engine.

Slow Analysis

• Issue: Analysis takes a very long time per move.
• Fix:
  1. This is normal for long games (50+ moves) or deep analysis.
  2. Ensure you're using a recent version of Stockfish (v16+).
  3. Close other CPU-intensive applications.
  4. The first analysis of a position is slowest; cached positions are instant.

API Issues

AI Summary Failed

• Error: "No summary generated" or "API error"
• Symptoms: AI Summary button shows error instead of game narrative.
• Fix:
  1. Verify your Internet connection.
  2. Check that your Gemini API Key in Settings is correct and active.
  3. Get a new key from Google AI Studio if needed.
  4. Ensure the key hasn't exceeded its free tier quota.

Chess.com Import Fails

• Error: "No games found" or "API error"
• Fix:
  1. Verify the username is spelled correctly (case-sensitive).
  2. Ensure the account is public (private accounts can't be fetched).
  3. Chess.com may have rate limits — wait a minute and try again.
  4. Try loading a specific game URL instead of username.

Lichess Import Fails

• Error: "Failed to fetch games" or empty game list
• Fix:
  1. Verify the username is spelled correctly.
  2. For better rate limits, add a Lichess API token in Settings.
  3. Generate a token at lichess.org/account/oauth/token with "Read games" scope.
  4. If loading by URL fails, try using just the 8-character game ID portion.

Lichess Token Not Working

• Error: 401 Unauthorized or token rejected
• Fix:
  1. Ensure the token has the correct scope ("Read games").
  2. Regenerate the token — they can expire.
  3. Copy the full token including the lip_ prefix.
  4. Paste carefully without extra spaces.

UI Issues

Stats Not Loading

• Issue: Stats page shows "Setup Required" or no data.
• Fix:
  1. Configure your usernames in Settings > Player Usernames.
  2. Ensure you've analyzed at least one game.
  3. The username must match the players in your analyzed games.
  4. Try clicking the Refresh button on the Stats page.

Board Theme Not Applying

• Issue: Changed board theme but board looks the same.
• Fix:
  1. Load a new game or navigate away and back to the Analysis page.
  2. Board themes apply on the next board render.
  3. If issue persists, restart the application.

Piece Theme Not Showing

• Issue: Changed piece theme but seeing default pieces.
• Fix:
  1. Ensure the piece theme folder exists in assets/pieces/.
  2. Each theme folder needs all 12 piece SVGs (wK, wQ, wR, wB, wN, wP, bK, bQ, bR, bB, bN, bP).
  3. Try selecting a different theme and switching back.

Splash Screen Stuck

• Issue: Application stays on splash screen and doesn't load.
• Fix:
  1. Wait 30 seconds — initial startup can be slow.
  2. Check chess_analyzer.log for error messages.
  3. Delete config.json to reset settings (you'll need to reconfigure).
  4. Ensure all required dependencies are installed.

Move List Icons Missing

• Issue: Classification icons don't appear in move list.
• Fix:
  1. Ensure assets/icons/ folder exists with all icon files.
  2. Try resizing the move list panel.
  3. If running from source, verify assets weren't accidentally deleted.

Data Issues

Games Not Saving

• Issue: Analyzed games don't appear in History.
• Fix:
  1. Ensure the analysis completes fully (100% progress).
  2. Check write permissions for the application directory.
  3. Verify analysis_cache.db file exists and isn't corrupted.
  4. Try clearing all data and re-analyzing.

CSV Import Fails

• Issue: Importing CSV shows error or no games added.
• Fix:
  1. Ensure CSV was exported from this application (format must match).
  2. Don't modify the CSV column headers.
  3. Check for special characters in player names that might break parsing.

Duplicate Games

• Issue: Same game appears multiple times in History.
• Fix:
  1. Right-click duplicates and delete them.
  2. This can happen if you analyze the same game from different sources.
  3. The app attempts to detect duplicates by game ID, but some slip through.

Application Logs

For advanced debugging, check the log file in the application's root directory:

# File location
chess_analyzer.log

# View last 100 lines (Windows PowerShell)
Get-Content chess_analyzer.log -Tail 100

# View last 100 lines (Mac/Linux)
tail -100 chess_analyzer.log

# Search for errors (PowerShell)
Select-String -Path chess_analyzer.log -Pattern "ERROR"

# Search for errors (Mac/Linux)
grep "ERROR" chess_analyzer.log

Common Error Messages

Getting Help

If your issue isn't listed above:

1. Check the GitHub Issues for known bugs.
2. Review chess_analyzer.log for specific error messages.
3. Visit the Official Website for FAQs.
4. Open a new issue on GitHub with:
   • Your OS and Python version
   • Steps to reproduce the issue
   • Relevant log excerpts