Troubleshooting Guide¶

Use this guide to diagnose installation, file loading, model configuration, and analysis issues in CodeXomics.

🚨 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. Open Settings → Model Providers (⌘, / Ctrl+,)
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();
   

Deep Gene Research Shows No Progress¶

Symptoms: A research run was started but the ChatBox shows nothing happening

Solutions:

1. Look above the input box, not in the conversation:
2. The research progress dock is pinned between the transcript and the composer so it never scrolls away
3. Its elapsed-time clock ticks every second while the run is alive, even when the percentage is unchanged

4. If the dock is collapsed, click its header to expand the run list

5. Confirm the run was actually queued:

6. A queued run answers with a task ID; if the reply has no task ID, the research never started

7. Check that the Deep Gene Research server is connected (MCP Servers in the ChatBox action bar)

8. Check the server connection if the dock turns red:

9. Polling gives up after several consecutive transport failures and the row shows the reason inline

10. Verify DGR_MCP_URL points at a running DGR process and that DGR_MCP_TOKEN matches its ACCESS_PASSWORD

11. Confirm polling is running:

    // In developer console — one entry per tracked run
    Array.from(window.chatManager.activeTasks.keys());
    

No ChangeSet Created After Research¶

Symptoms: Research completed, but no annotation ChangeSet appeared for review

Solutions:

1. Read the reason in the completion message — creation is deliberately fail-closed and always says why:
2. draft_requires_evidence — no evidence-backed claims safe enough to propose
3. draft_requires_target — the proposal is not bound to an exact gene in the loaded genome
4. not needed — the gene already carries everything the research proposed

5. Archive DGR research task … as a gene report first — the run was not target-bound

6. Load the genome before researching:

7. A ChangeSet needs a resolvable target; with no primary annotations loaded, nothing can be proposed

8. For FASTA + GFF, merge the GFF features into the primary annotation set first

9. Use a target-bound run for full provenance:

10. start_annotation_research resolves the exact CDS target and sends its current-annotation snapshot to DGR, which is what lets the report be archived and the proposal validated

11. A raw deep-gene-research call cannot satisfy that chain retroactively

12. Check whether it already exists:

13. Re-checking a completed task returns the existing ChangeSet rather than creating a second one
14. List pending proposals with the list_annotation_changesets tool or the Review panel

📁 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

Reads Track Is Empty¶

1. Load the reference genome used for alignment. Compare the selected chromosome or contig with the names in the SAM/BAM header. If the track reports that the current chromosome is missing from the BAM, switch to a matching reference or load the matching assembly.
2. Confirm that Reads is visible under Display → Track Control. Check the mapping-quality and secondary/supplementary alignment filters, then navigate to a region with known coverage.
3. For BAM, keep the matching .bai or .csi index in the same directory as the file. CodeXomics checks both sample.bam.bai and sample.bai, and the corresponding .csi names.

🖥️ 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.