Skip to content

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 LLM Providers
  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

πŸ–₯️ 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

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.