Troubleshooting Guide¶

This guide helps you resolve common issues encountered while using CodeXomics v0.722.

🚨 Common Installation Issues¶

Application Won't Start¶

Symptoms: Application fails to launch or shows a white screen

Solutions:

1. Check system requirements:
2. Ensure you have sufficient RAM (6GB minimum)
3. Verify your operating system is supported

4. Update to the latest OS version if needed

5. Clear application data:

# macOS
rm -rf ~/Library/Application\ Support/codexomics

# Windows
del /s "%APPDATA%\codexomics"

# Linux
rm -rf ~/.config/codexomics

1. Reinstall the application:
2. Completely uninstall the current version
3. Download the latest release
4. Install with administrator privileges

Permission Errors¶

Symptoms: "Permission denied" or "Access is denied" errors

Solutions:

1. Run as administrator (Windows) or with sudo (Linux/macOS)
2. Check file permissions for your data directory
3. Disable antivirus temporarily during installation
4. Add application to firewall exceptions

Electron Framework Issues¶

Symptoms: "Failed to load Electron" or framework-related errors

Solutions:

1. Update Node.js to the latest LTS version
2. Clear npm cache:

   npm cache clean --force
   

3. Reinstall dependencies:

   rm -rf node_modules package-lock.json
   npm install
   

🔧 Runtime Issues¶

Version Management Errors¶

Symptoms: SyntaxError: Unexpected token 'export' or version-related errors

Solutions:

1. Update to latest version that includes the unified version management system
2. Clear module cache:

   npm run version-sync
   npm run version-validate
   

3. Check for mixed module syntax in custom plugins

Memory Issues¶

Symptoms: Application becomes slow or crashes with large files

Solutions:

1. Increase system memory allocation
2. Close other applications to free up RAM
3. Use streaming mode for files larger than 500MB
4. Enable Simple Mode for better performance:
5. Go to View → Simple Mode

Plugin System Issues¶

Symptoms: Plugins not loading or marketplace errors

Solutions:

1. Check plugin compatibility with current version
2. Clear plugin cache:

   rm -rf ~/.codexomics/plugins
   

3. Verify plugin marketplace server is accessible
4. Check plugin dependencies are installed

🤖 AI Assistant Issues¶

AI Assistant Not Responding¶

Symptoms: Chat doesn't work or returns errors

Solutions:

1. Check API key configuration:
2. Go to Options → Configure LLMs
3. Verify API key is correct and active

4. Test connection using "Test Connection" button

5. Verify internet connection:

6. Ensure stable internet for cloud providers

7. Check firewall settings for API access

8. Try different AI provider:

9. Switch between OpenAI, Anthropic, or Google
10. Use local LLM (Ollama) for offline operation

Conversation Evolution Issues¶

Symptoms: Conversation history not recording or analysis errors

Solutions:

1. Check conversation recording settings:
2. Open developer console (F12)
3. Look for conversation recording errors

4. Restart application to reset recording

5. Verify storage permissions:

6. Check write permissions in user data directory

7. Clear conversation history to reset storage

8. Reset conversation system:

   // In developer console
   window.conversationEvolutionManager.resetSystem();
   

📁 File Loading Issues¶

Large File Performance¶

Symptoms: Application becomes unresponsive with large genomic files

Solutions:

1. Use file streaming for files > 100MB
2. Enable BAM file handling for sequencing data
3. Reduce visible track count for large genomes
4. Use indexed file formats when available

File Format Issues¶

Symptoms: Files not loading or parsing errors

Solutions:

1. Verify file format is supported:
2. FASTA, GenBank, GFF/GTF, BED, VCF, SAM/BAM, WIG, KGML
3. Check file integrity:
4. Ensure files are not corrupted
5. Verify proper line endings (Unix vs Windows)
6. Convert file format if needed

Path Resolution Issues¶

Symptoms: "File not found" errors with valid files

Solutions:

1. Use absolute paths instead of relative paths
2. Check for special characters in file names
3. Verify file permissions are readable
4. Move files to project directory for better management

🖥️ User Interface Issues¶

Track Rendering Problems¶

Symptoms: Tracks not displaying correctly or visual glitches

Solutions:

1. Refresh track display:
2. Right-click track → Refresh

3. Or reload the current view

4. Check track settings:

5. Verify track height settings
6. Reset track order if needed

7. Toggle track visibility

8. Clear graphics cache:

9. Restart application
10. Reset window positions

Menu Issues¶

Symptoms: Menu items not working or menu height errors

Solutions:

1. Restart application to reset menu state
2. Check for menu conflicts between windows
3. Reset UI preferences:

   rm ~/.codexomics/ui-preferences.json
   

Project Manager Issues¶

Symptoms: Project Manager not loading or view mode problems

Solutions:

1. Check project file integrity:
2. Verify .prj.GAI file is valid XML

3. Check for missing project files

4. Reset view mode:

5. Switch between Grid/List/Details views

6. Restart Project Manager window

7. Clear project cache:

   rm ~/.codexomics/projects.json
   

🔬 Analysis Tool Issues¶

BLAST Tool Problems¶

Symptoms: BLAST tools not working or database errors

Solutions:

1. Install BLAST+ tools:
2. Use Tools → Install BLAST+

3. Or install manually from NCBI

4. Check database configuration:

5. Verify database paths are correct

6. Update database configurations

7. Memory map errors:

8. Increase system memory limits
9. Use smaller database segments

KGML Pathway Viewer Issues¶

Symptoms: Pathway viewer not loading or cytoscape errors

Solutions:

1. Check internet connection for CDN resources
2. Clear browser cache in developer tools
3. Verify KGML file format is valid XML
4. Restart pathway viewer tool

STRING Networks Problems¶

Symptoms: "cytoscape is not defined" errors

Solutions:

1. Check CDN availability:
2. Verify internet connection

3. Wait for library loading timeout

4. Use fallback CDN sources:

5. Application automatically tries backup sources

6. Check developer console for loading status

7. Restart network visualization tool

🔧 Advanced Troubleshooting¶

Developer Console Debugging¶

Access Developer Console:

• Press F12 or Ctrl+Shift+I
• Look for error messages in Console tab
• Check Network tab for failed requests

Common Error Patterns:

1. Module loading errors: Check script loading order
2. API call failures: Verify network connectivity
3. Memory errors: Monitor memory usage in Performance tab

Log File Analysis¶

Log Locations:

• macOS: ~/Library/Logs/codexomics/
• Windows: %APPDATA%\codexomics\logs\
• Linux: ~/.config/codexomics/logs/

Key Log Files:

• main.log: Main process errors
• renderer.log: UI and visualization errors
• plugin.log: Plugin-related issues

Performance Optimization¶

For Large Datasets:

1. Enable hardware acceleration in system settings
2. Increase Node.js memory limit:

   export NODE_OPTIONS="--max-old-space-size=8192"
   

3. Use Simple Mode for reduced UI complexity
4. Close unused tracks and tools

For Slow Performance:

1. Check system resource usage (CPU, Memory)
2. Disable unnecessary features temporarily
3. Restart application to clear caches
4. Update graphics drivers

📞 Getting Additional Help¶

Before Reporting Issues¶

1. Update to latest version of CodeXomics
2. Check existing issues on GitHub
3. Gather system information:
4. Operating system and version
5. Available memory and storage
6. Error messages and logs

Reporting Bugs¶

Include in Bug Reports:

• Detailed steps to reproduce the issue
• Expected vs actual behavior
• System specifications
• Error messages and stack traces
• Screenshots or screen recordings

Where to Report:

• GitHub Issues: For bugs and feature requests
• Email Support: For sensitive or complex issues
• Community Forums: For general questions

Emergency Recovery¶

Complete Reset (last resort):

1. Backup important projects and data
2. Uninstall application completely
3. Clear all application data directories
4. Reinstall latest version
5. Restore project data if needed

🔍 Diagnostic Commands¶

Version Validation¶

npm run version-validate

System Health Check¶

# Check Node.js version
node --version

# Check npm version
npm --version

# Check available memory
# macOS/Linux
free -h

# Windows
wmic OS get TotalVisibleMemorySize,FreePhysicalMemory /format:list

Plugin System Check¶

# Run the Vitest suite
npm test

# Check plugin marketplace connectivity
curl -I https://codexomics-marketplace.com/api/health

📋 Quick Reference¶

Common Keyboard Shortcuts¶

• F12: Open Developer Console
• Ctrl+Shift+R: Hard reload
• Ctrl+Shift+O: Open project
• Ctrl+F: Search
• Ctrl+Plus/Minus: Zoom

Emergency Actions¶

• Force quit: Ctrl+Alt+T (Task Manager)
• Safe mode: Start with --safe-mode flag
• Reset settings: Delete config directory
• Clear cache: Restart application

Still having issues? Contact our support team with detailed information about your problem, including system specifications and error messages.

This guide covers CodeXomics 0.722.0. Check for updates to both the application and this documentation.