Troubleshooting.md - himent12/FlashGenie GitHub Wiki

Install with --no-dependencies and manual resolution

pip install flashgenie --no-dependencies pip install -r requirements.txt


## 🎯 **Startup Issues**

### Command Not Found

**Problem**: `flashgenie` command not found after installation.

**Solutions**:

```bash
# Check installation
pip show flashgenie

# Use module syntax instead
python -m flashgenie

# Add to PATH (if installed in user directory)
# Add this to your .bashrc or .zshrc:
export PATH="$HOME/.local/bin:$PATH"

# On Windows, check if Scripts directory is in PATH
echo %PATH%
# Add if needed: setx PATH "%PATH%;C:\Users\YourUsername\AppData\Local\Programs\Python\Python39\Scripts"

Import Errors

Problem: Import errors when starting FlashGenie.

Solutions:

# Reinstall with all dependencies
pip uninstall -y flashgenie
pip install flashgenie

# Check Python version
python --version
# Make sure it's 3.8 or higher

# Install missing dependency manually
pip install missing_package_name

🎯 Data Issues

Deck Loading Failures

Problem: Unable to load or access decks.

Solutions:

# Check deck existence
python -m flashgenie list

# Repair database
python -m flashgenie maintenance repair-database

# Check file permissions
ls -la ~/.flashgenie/

# Restore from backup
python -m flashgenie backup restore latest

Corrupt Data Files

Problem: Data corruption or database errors.

Solutions:

# Verify database integrity
python -m flashgenie maintenance verify-database

# Rebuild database
python -m flashgenie maintenance rebuild-database

# Restore from backup
python -m flashgenie backup list
python -m flashgenie backup restore backup_20240601.fgb

Import Failures

Problem: Unable to import flashcards from files.

Solutions:

# Check file format
file my_cards.csv

# Try with explicit format
python -m flashgenie import my_cards.csv --format csv --delimiter ","

# Check encoding
python -m flashgenie import my_cards.csv --encoding utf-8

# Import with verbose logging
python -m flashgenie import my_cards.csv --verbose

🎯 Performance Issues

Slow Operation

Problem: FlashGenie runs slowly, especially with large decks.

Solutions:

# Enable performance optimizations
python -m flashgenie config set performance.optimize true

# Reduce memory usage
python -m flashgenie config set memory.max_cards_in_memory 5000

# Enable lazy loading
python -m flashgenie config set performance.lazy_loading true

# Analyze performance
python -m flashgenie maintenance analyze-performance

High Memory Usage

Problem: FlashGenie uses excessive memory.

Solutions:

# Limit memory usage
python -m flashgenie config set memory.cache_size_mb 256

# Enable garbage collection
python -m flashgenie config set memory.aggressive_gc true

# Split large decks
python -m flashgenie split-deck "Large Deck" --max-cards 1000

Database Slowdowns

Problem: Database operations become slow over time.

Solutions:

# Optimize database
python -m flashgenie maintenance optimize-database

# Rebuild indexes
python -m flashgenie maintenance rebuild-indexes

# Compact database
python -m flashgenie maintenance compact-database

🎯 Quiz Session Issues

Session Crashes

Problem: Quiz sessions crash unexpectedly.

Solutions:

# Run with error logging
python -m flashgenie quiz --debug

# Check for problematic cards
python -m flashgenie validate "Deck Name" --fix-issues

# Update to latest version
pip install --upgrade flashgenie

# Run with reduced features
python -m flashgenie quiz --safe-mode

Incorrect Scheduling

Problem: Cards appear too frequently or not frequently enough.

Solutions:

# Reset scheduling data
python -m flashgenie reset-scheduling "Deck Name"

# Adjust algorithm parameters
python -m flashgenie config set spaced_repetition.interval_modifier 0.8

# Manually review scheduling
python -m flashgenie analyze-scheduling "Deck Name"

# Switch algorithm
python -m flashgenie config set spaced_repetition.algorithm sm2

Answer Evaluation Issues

Problem: Correct answers marked wrong or vice versa.

Solutions:

# Adjust strictness
python -m flashgenie config set quiz.answer_strictness 0.8

# Disable case sensitivity
python -m flashgenie config set quiz.case_sensitive false

# Enable partial matching
python -m flashgenie config set quiz.allow_partial_answers true

# Review answer comparison settings
python -m flashgenie config list quiz.answer_*

🎯 UI Issues

Display Problems

Problem: Text display issues, formatting problems, or visual glitches.

Solutions:

# Switch to basic UI mode
python -m flashgenie config set ui.mode basic

# Reset UI settings
python -m flashgenie config reset ui.*

# Check terminal capabilities
python -m flashgenie check-terminal

# Use alternative renderer
python -m flashgenie config set ui.renderer simple

Color Issues

Problem: Colors not displaying correctly or causing readability issues.

Solutions:

# Disable colors
python -m flashgenie config set ui.use_colors false

# Use high contrast theme
python -m flashgenie theme set high-contrast

# Set specific color scheme
python -m flashgenie config set ui.color_scheme basic

# Check terminal color support
python -m flashgenie check-terminal --color-test

Input Problems

Problem: Input not recognized or keyboard issues.

Solutions:

# Use alternative input mode
python -m flashgenie config set ui.input_mode basic

# Disable special key handling
python -m flashgenie config set ui.special_keys false

# Check keyboard layout
python -m flashgenie check-keyboard

# Use numeric input for confidence
python -m flashgenie config set quiz.confidence_input_style numeric

🎯 Configuration Issues

Settings Not Applied

Problem: Configuration changes don't take effect.

Solutions:

# Verify configuration
python -m flashgenie config list

# Reset specific setting
python -m flashgenie config reset setting.name

# Force configuration reload
python -m flashgenie config reload

# Check config file location
python -m flashgenie config path

Config File Corruption

Problem: Configuration file is corrupted.

Solutions:

# Reset to defaults
python -m flashgenie config reset --all

# Restore from backup
python -m flashgenie config restore-backup

# Manually edit config
python -m flashgenie config edit

# Check file permissions
ls -la ~/.flashgenie/config.json

Profile Switching Issues

Problem: Unable to switch between configuration profiles.

Solutions:

# List available profiles
python -m flashgenie config list-profiles

# Create new profile
python -m flashgenie config create-profile "new-profile"

# Force profile switch
python -m flashgenie config use-profile "profile-name" --force

# Reset profile
python -m flashgenie config reset-profile "profile-name"

🎯 Advanced Troubleshooting

Diagnostic Tools

Use FlashGenie's built-in diagnostic tools:

# Run system check
python -m flashgenie diagnostics

# Generate diagnostic report
python -m flashgenie diagnostics report --output diagnostic_report.txt

# Check for common issues
python -m flashgenie diagnostics check-common-issues

# Verify installation
python -m flashgenie diagnostics verify-installation

Logging

Enable and use logging for troubleshooting:

# Enable debug logging
python -m flashgenie config set logging.level debug

# Log to file
python -m flashgenie config set logging.file flashgenie_debug.log

# View recent logs
python -m flashgenie logs show

# Clear logs
python -m flashgenie logs clear

Recovery Mode

Use recovery mode for serious issues:

# Start in recovery mode
python -m flashgenie --recovery-mode

# Export all data in recovery mode
python -m flashgenie --recovery-mode export-all backup_export

# Rebuild database in recovery mode
python -m flashgenie --recovery-mode rebuild-database

# Reset to factory defaults
python -m flashgenie --recovery-mode factory-reset

🎯 Common Error Messages

"Database locked"

Problem: Database is locked by another process.

Solutions:

# Check for other instances
ps aux | grep flashgenie

# Force unlock database
python -m flashgenie maintenance force-unlock-database

# Restart application
killall python  # Be careful with this command
python -m flashgenie

"Deck not found"

Problem: Referenced deck cannot be found.

Solutions:

# List available decks
python -m flashgenie list

# Check for typos in name
python -m flashgenie find "partial-name"

# Check storage location
python -m flashgenie config get storage.path

# Restore from backup
python -m flashgenie backup restore latest

"Invalid card format"

Problem: Card format is invalid or corrupted.

Solutions:

# Validate cards
python -m flashgenie validate "Deck Name"

# Fix card formatting
python -m flashgenie repair "Deck Name"

# Export and reimport
python -m flashgenie export "Deck Name" temp_export.csv
python -m flashgenie import temp_export.csv --name "Fixed Deck"

🚀 Getting Help

If you're still experiencing issues:

Check Documentation: Review the complete documentation at docs.flashgenie.app
Community Support: Ask the community at community.flashgenie.app
GitHub Issues: Report bugs at github.com/flashgenie/flashgenie/issues
Discord: Join our Discord server at discord.gg/flashgenie
Email Support: Contact support at [email protected]

🚀 Next Steps

Complete Command Reference - All CLI commands with examples
Advanced Usage Patterns - Power-user techniques and workflows
Data Management - Import, export, and backup strategies

FlashGenie v1.5.0 | Last updated: June 2025