Skip to content

Troubleshooting Guide

Common issues and solutions when using or building Rodrigolab's Flow Cytometry Analyzer.

Installation Issues

macOS: "App is damaged and can't be opened"

This error occurs because the app is not code-signed. macOS Gatekeeper blocks unsigned apps downloaded from the internet. This is a security feature, not an actual problem with the app.

Solution (choose one method):

Method 1: Remove quarantine attribute (Recommended) 

xattr -cr "/Applications/Rodrigolab's Flow Cytometry Analyzer.app"
Then open the app normally from Applications.

Method 2: Right-click to open - Right-click (or Control-click) the app in Applications - Select "Open" from the context menu - Click "Open" in the security dialog - This only needs to be done once

Method 3: System Settings - Go to System Settings > Privacy & Security (or System Preferences > Security & Privacy on older macOS) - Scroll down to find the blocked app message - Click "Open Anyway" - Confirm by clicking "Open"

After using any of these methods, you can open the app normally in the future.

Windows: SmartScreen warning "Windows protected your PC"

This warning appears because the application is not code-signed. Windows Defender SmartScreen blocks unrecognized applications as a security measure. This is normal for unsigned software.

Solution (choose one method):

Method 1: Use "More info" (Recommended) 1. When the SmartScreen warning appears, click "More info" 2. Click "Run anyway" to proceed with installation 3. This only needs to be done once per download

Method 2: Unblock the file 1. Right-click the downloaded .msi file 2. Select "Properties" 3. If you see an "Unblock" checkbox at the bottom, check it 4. Click "OK" 5. Run the installer normally

Method 3: Windows Security Settings 1. Open Windows Security (Settings > Privacy & Security > Windows Security) 2. Go to "App & browser control" 3. Under "Check apps and files", you can temporarily lower the protection level (not recommended for long-term)

Note: After the first installation, Windows will remember your choice and future updates should install without the warning.

Linux: Dependency errors when installing DEB

Solution: 

sudo apt-get install -f

This will install missing dependencies.

Runtime Issues

Application won't start

Check: 1. System requirements are met 2. No other instance is running 3. Check system logs for errors

macOS: 

# Check Console.app for errors
# Or from terminal:
log show --predicate 'process == "Rodrigolab'" --last 5m

Linux: 

# Run from terminal to see errors
./Rodrigolab\'s\ Flow\ Cytometry\ Analyzer_*.AppImage

FCS file won't load

Possible causes: 1. File is corrupted 2. Unsupported FCS format version 3. File is locked by another application

Solutions: - Try a different FCS file - Check file permissions - Ensure file isn't open in another program

Plot is blank or shows no data

Check: 1. Data loaded successfully (check file info) 2. Channels are selected 3. Data range is visible (try resetting zoom) 4. Log scale settings (try switching to linear)

Solution: - Click "Reset" button to reset zoom - Try different channel combinations - Check if data values are valid (not all zeros)

Selection not working

Check: 1. You're using left-click to draw (not right-click) 2. Selection has at least 3 points 3. Plot is not in pan mode

Solution: - Make sure you're left-clicking and dragging - Release mouse to close selection - Right-click is for panning, not selection

Export fails

Check: 1. You have write permissions to the output directory 2. Disk space is available 3. File path is valid

Solutions: - Try a different output location - Check disk space: df -h (Linux/macOS) or check in File Explorer (Windows) - Ensure output directory exists

Build Issues

"Tauri CLI not found"

Solution: 

cargo install tauri-cli --locked

"Target not installed"

Solution: 

rustup target add <target-triple>

Common targets: - aarch64-apple-darwin (macOS ARM64) - x86_64-apple-darwin (macOS Intel) - x86_64-pc-windows-msvc (Windows) - x86_64-unknown-linux-gnu (Linux)

Build fails with icon errors

Solution: 1. Check that all icon files exist in src-tauri/icons/: - icon.png - icon.icns (macOS) - icon.ico (Windows) - Size variants (32x32.png, 128x128.png, etc.)

  1. Verify tauri.conf.json has correct icon paths

Linux: Missing system dependencies

Solution: Install all required packages: 

sudo apt-get update
sudo apt-get install -y \
  libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libxdo-dev \
  libssl-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  patchelf \
  libgtk-3-dev

Windows: Linker errors

Solution: 1. Install Visual C++ Build Tools 2. Restart terminal/IDE after installation 3. Ensure Windows SDK is installed

macOS: Code signing warnings

Note: These are normal for local builds and don't prevent the app from running.

For distribution: 1. Set up Apple Developer account 2. Configure signing in tauri.conf.json 3. See Tauri code signing guide

Build is very slow

Optimizations: 1. Use release build: cargo tauri build --release 2. Disable debug symbols (if not needed) 3. Use cargo build instead of cargo tauri build for Rust-only changes

Out of memory during build

Solution: 1. Close other applications 2. Increase swap space (Linux) 3. Build on a machine with more RAM 4. Use GitHub Actions for builds

Performance Issues

Application is slow

Check: 1. File size (very large FCS files may be slow) 2. Number of points displayed 3. System resources

Solutions: - Close other applications - Try with a smaller dataset first - Check system memory usage

Plot rendering is slow

Solutions: - Reduce zoom level (fewer points to render) - Disable "Show excluded points" if enabled - Close and reopen the application

Getting Help

If you're still experiencing issues:

  1. Check the logs:
  2. macOS: Console.app
  3. Linux: Run from terminal

  4. Windows: Event Viewer

  5. Search existing issues:

  6. GitHub Issues

  7. Create a new issue:

  8. Include your OS and version
  9. Describe the problem clearly
  10. Include error messages

  11. Attach relevant files (if possible)

  12. Check documentation:

  13. Tauri documentation
  14. FCS file format specification

Reporting Bugs

When reporting a bug, please include:

  1. System information:
  2. OS and version
  3. Application version

  4. Architecture (ARM64, x86_64, etc.)

  5. Steps to reproduce:

  6. Clear, numbered steps

  7. Sample data (if possible)

  8. Expected vs. actual behavior:

  9. What should happen

  10. What actually happens

  11. Error messages:

  12. Full error text

  13. Screenshots if helpful

  14. Additional context:

  15. FCS file format/version
  16. File size
  17. Any custom configurations