Skip to content

TROUBLESHOOTING

Jump to bottom
github-actions[bot] edited this page Sep 16, 2026 · 2 revisions

Troubleshooting Guide

This guide provides solutions to common issues encountered when using DRerio LogAI.

Table of Contents

  1. Installation Issues
  2. Camera and Video Issues
  3. Detection and Tracking Issues
  4. Performance Issues
  5. GPU and Hardware Issues
  6. Analysis and Results Issues
  7. Application Errors
  8. Configuration Issues

Installation Issues

Poetry installation fails

Problem: poetry install command fails with dependency errors

Solutions:

  1. Ensure Python 3.12 or 3.13 (3.14 is NOT supported: the pinned NumPy has no wheel for it, so the install tries to compile from source and fails):

    poetry run python -V   # Must report 3.12.x or 3.13.x

    If it reports anything else, rebuild the environment: poetry env use 3.12 then poetry install.

  2. Update Poetry:

    poetry self update

  3. Clear Poetry cache:

    poetry cache clear pypi --all
poetry install

  4. Force reinstall:

    rm -rf .venv
poetry install

  5. Check setuptools version (must be <81):

    poetry run pip list | grep setuptools
# Should show setuptools < 81

ModuleNotFoundError after installation

Problem: ModuleNotFoundError: No module named 'zebtrack'

Solutions:

  1. Run through Poetry (poetry shell was removed in Poetry 2.0 and moved to the poetry-plugin-shell plugin; prefer poetry run):

    poetry run zebtrack

  2. Verify installation:

    poetry show zebtrack
# Should display package info

  3. Reinstall in editable mode:

    poetry install

ImportError: DLL load failed (Windows)

Problem: ImportError: DLL load failed while importing _imaging

Solutions:

  1. Install Visual C++ Redistributables:

    • Download from Microsoft
    • Install and restart computer

  2. Reinstall Pillow:

    poetry run pip uninstall Pillow
poetry run pip install Pillow

  3. Check Python architecture:

    python -c "import struct; print(struct.calcsize('P') * 8)"
# Should show 64 (not 32)

Camera and Video Issues

Camera Not Found

Problem: Error message "Camera ID 0 not available" or "Cannot open camera"

Step-by-Step Solutions:

1. Verify Camera Connection

  • Check USB cable is fully inserted
  • Try different USB port (prefer USB 3.0)
  • Test camera in other applications (Zoom, Skype)

2. Check Camera Permissions (Windows)

  1. Open Settings → Privacy & Security → Camera
  2. Enable "Let apps access your camera"
  3. Enable "Let desktop apps access your camera"
  4. Restart application

3. Check Camera Permissions (Linux)

# Check if user is in video group
groups $USER

# Add user to video group if needed
sudo usermod -a -G video $USER
# Log out and log back in

# Check camera devices
ls -l /dev/video*

4. Try Different Camera ID

  1. Open File → Settings
  2. Navigate to Camera section
  3. Try camera IDs: 0, 1, 2, 3
  4. Click Test Camera for each ID

5. Check Camera Driver (Windows)

  1. Open Device Manager (Win+X → Device Manager)
  2. Expand Cameras or Imaging devices
  3. Right-click camera → Update driver
  4. If yellow warning icon: Uninstall device → Restart computer

6. Restart Camera Service (Windows)

# Run as Administrator
Get-PnpDevice | Where-Object {$_.FriendlyName -like '*camera*'} | Disable-PnpDevice -Confirm:$false
Start-Sleep -Seconds 2
Get-PnpDevice | Where-Object {$_.FriendlyName -like '*camera*'} | Enable-PnpDevice -Confirm:$false

Video file won't load

Problem: Error when loading video file

Solutions:

  1. Check file format:

    • Supported: MP4, AVI, MOV, MKV
    • Use VLC or FFmpeg to verify file integrity

  2. Try re-encoding:

    # Using FFmpeg
ffmpeg -i input.mp4 -c:v libx264 -preset medium -crf 23 output.mp4

  3. Check file path:

    • Avoid special characters in filename
    • Avoid very long paths (>260 chars on Windows)
    • Use absolute paths, not relative

  4. Verify codec:

    ffmpeg -i video.mp4
# Look for Video: h264 or Video: hevc

  5. Copy file locally:

    • If on network drive, copy to local disk first

Camera image is black or frozen

Problem: Camera opens but shows black screen or frozen image

Solutions:

  1. Check camera exposure settings:

    • May be auto-adjusting to lighting
    • Wait 5-10 seconds for auto-exposure

  2. Improve lighting:

    • Ensure adequate light in environment
    • Avoid pointing camera at bright light source

  3. Test camera externally:

    import cv2
cap = cv2.VideoCapture(0)
ret, frame = cap.read()
if ret:
    cv2.imshow('Test', frame)
    cv2.waitKey(0)
cap.release()

  4. Update camera firmware (if available from manufacturer)

  5. Try different resolution:

    • In settings, try lower resolution (720p instead of 1080p)

Detection and Tracking Issues

Low Detection Accuracy

Problem: Many missed detections or false positives

Immediate Solutions:

For Too Many False Positives (detecting debris, shadows)

  1. Increase confidence threshold:

    • Current: 0.5 → Try: 0.6 or 0.7
    • In Wizard Step 4 or Settings → Detection

  2. Clean environment:

    • Remove debris from tank
    • Clean camera lens
    • Use plain background (avoid gravel, plants)

  3. Improve lighting:

    • Add diffuse lighting (no harsh shadows)
    • Eliminate reflections and glare
    • Use consistent lighting (no flickering)

For Too Many Misses (not detecting fish)

  1. Lower confidence threshold:

    • Current: 0.5 → Try: 0.4 or 0.35
    • Increases sensitivity

  2. Check video quality:

    • Increase resolution (720p → 1080p)
    • Ensure camera is in focus
    • Verify sufficient contrast (fish vs background)

  3. Try different model:

    • Switch YOLO ↔ OpenVINO
    • Try different YOLO variant (if custom models available)

General Accuracy Improvements

  1. Calibrate camera:

    • Ensure camera is perpendicular to water surface
    • Minimize lens distortion (use good quality lens)
    • Fix camera position (no movement)

  2. Optimize video settings:

    • Frame rate: 30 FPS (not too high or low)
    • Bitrate: High (minimize compression)
    • Codec: H.264 (good quality/size balance)

  3. Subject visibility:

    • Ensure fish is visually distinct from background
    • Adequate size in frame (fish should be >30 pixels)
    • Good contrast (dark fish on light background or vice versa)

  4. Consider custom model:

    • If using non-standard species, train custom model
    • See docs/MODEL_TRAINING.md (coming soon)

Track IDs keep changing

Problem: Subject loses track ID frequently, causing incorrect metrics

Understanding the Issue: Track ID changes (re-identification failures) occur when:

  • Subjects occlude each other (multi-subject tracking)
  • Subject exits and re-enters frame
  • Detection gaps (subject temporarily not detected)
  • Similar-looking subjects

Solutions:

  1. Improve detection consistency:

    • Increase confidence threshold (more reliable detections)
    • Improve video quality
    • Ensure continuous detection (no gaps)

  2. For single-subject tracking:

    • Ensure only one subject in frame
    • Verify not detecting reflections or debris
    • May need to manually filter tracks by duration

  3. For multi-subject tracking:

    • ID swaps are more common (expected behavior)
    • Use track-by-track analysis (separate metrics per ID)
    • Consider analyzing subjects individually if possible

  4. Post-processing:

    • Merge short tracks that are likely same subject
    • Filter tracks by minimum duration
    • Use custom scripts for track reconciliation

No detections in entire video

Problem: Analysis completes but 0 detections found

Solutions:

  1. Verify model loaded:

    • Check Help → System Info → Model status
    • If error, reinstall model or specify model path

  2. Lower confidence threshold drastically:

    • Try 0.1 or 0.2 to see if any detections occur

  3. Check frame extraction:

    • Verify video is actually playing (not corrupted)
    • Check frame count > 0 in video metadata

  4. Test on sample video:

    • Try analysis on known-good video (e.g., demo video)
    • If works, issue is with your specific video

  5. Check ROI configuration:

    • If ROI is defined, ensure it covers subject location
    • Try removing ROI constraints

  6. Verify subject is visible:

    • Manually inspect video frames
    • Ensure subject is not too small (<10 pixels)

Performance Issues

Slow Performance

Problem: Analysis is very slow (<5 FPS)

Quick Diagnostics:

Check current performance:

  • During analysis, note "Processing Speed" (FPS)
  • Compare to expected: GPU 25-60 FPS, CPU 5-15 FPS

Solutions by Cause:

1. GPU Not Being Used

Check GPU status:

poetry run python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

If False:

  • Install CUDA Toolkit: NVIDIA CUDA Downloads

  • Install cuDNN: NVIDIA cuDNN

  • Reinstall PyTorch with CUDA:

    poetry run pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

If True but still slow:

  • Check GPU memory usage: nvidia-smi
  • Close other GPU applications
  • Reduce batch size in settings

2. Video Resolution Too High

Solution: Reduce resolution

# In config.local.yaml
camera:
  desired_width: 1280   # Down from 1920
  desired_height: 720   # Down from 1080

Or pre-process video:

ffmpeg -i input_4k.mp4 -vf scale=1920:1080 output_1080p.mp4

3. Insufficient RAM

Check RAM usage:

  • Windows: Task Manager → Performance → Memory
  • Linux: htop or free -h

Solutions:

  • Close other applications (browsers, etc.)
  • Increase virtual memory (Windows: System → Advanced → Performance Settings)
  • Reduce performance.max_parallel_videos in settings
  • Process shorter video segments

4. Hard Drive Bottleneck

Solutions:

  • Use SSD instead of HDD for temporary files

  • Set temporary directory to SSD:

    export TMPDIR=/path/to/ssd/tmp  # Linux
set TMP=D:\tmp  # Windows

  • Disable real-time antivirus scanning on output directory

5. CPU Throttling (Laptops)

Solutions:

  • Plug in power adapter (don't use battery)
  • Check CPU throttling: Windows → Power Options → High Performance
  • Ensure adequate cooling (use laptop cooling pad)
  • Clean dust from vents

Application freezes during analysis

Problem: Application becomes unresponsive

Solutions:

  1. Wait longer:

    • Large videos may appear frozen but are processing
    • Check CPU/GPU usage to verify activity

  2. Reduce memory usage:

    • Close browser, other applications
    • Reduce video resolution
    • Enable frame skipping

  3. Update graphics drivers:

  4. Disable real-time previews:

    # In config.local.yaml
ui_features:
  enable_preview_updates: false

  5. Run in terminal mode (bypass GUI):

    poetry run zebtrack --no-gui --video input.mp4 --output results/

GPU and Hardware Issues

GPU Not Detected

Problem: System Info shows "GPU: Not Available" despite having NVIDIA GPU

Step-by-Step Fix:

1. Verify GPU is Working

# Windows: Open Device Manager
Win+X → Device Manager → Display adapters
# Should show NVIDIA GPU

# Linux:
lspci | grep -i nvidia

2. Check NVIDIA Drivers

nvidia-smi
# Should display GPU info, driver version, CUDA version

If command not found:

3. Verify CUDA Installation

nvcc --version
# Should show CUDA compiler version

If command not found:

4. Check PyTorch CUDA Support

poetry run python -c "import torch; print(torch.version.cuda)"
# Should show CUDA version (e.g., 11.8)

If None:

  • PyTorch is CPU-only version

  • Reinstall with CUDA support:

    poetry run pip uninstall torch torchvision
poetry run pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

5. Restart Application

# Fully close application
# Reopen
poetry run zebtrack
# Check Help → System Info

CUDA Out of Memory Error

Problem: RuntimeError: CUDA out of memory

Solutions:

  1. Reduce batch size:

    # In config.local.yaml
performance:
  detection_batch_size: 1 # Down from 4 or 8

  2. Lower video resolution (see Slow Performance)

  3. Close other GPU applications:

    # Check GPU memory usage
nvidia-smi

# Kill GPU processes if needed
# (use Task Manager or kill command)

  4. Enable GPU memory growth (automatic in TensorFlow, manual in PyTorch):

    # Advanced users: modify src/zebtrack/plugins/yolo_plugin.py
import torch
torch.cuda.empty_cache()

  5. Use smaller model:

    • YOLOv8n (nano) instead of YOLOv8l (large)
    • Configure in Wizard Step 4

Arduino not responding

Problem: Arduino-based triggers not working

Solutions:

  1. Verify Arduino connection:

    • Check USB cable connected
    • LED on Arduino should be on
    • Try different USB port

  2. Check COM port (Windows):

    • Device Manager → Ports (COM & LPT)

    • Note COM port number (e.g., COM3)

    • Update in config:

      arduino:
  port: "COM3" # Adjust to your port

  3. Check device path (Linux):

    ls -l /dev/ttyUSB* /dev/ttyACM*
# Note device (e.g., /dev/ttyUSB0)
    arduino:
  port: "/dev/ttyUSB0"

  4. Verify permissions (Linux):

    sudo usermod -a -G dialout $USER
# Log out and log back in

  5. Test Arduino separately:

    • Open Arduino IDE
    • Upload simple sketch (Blink)
    • Verify working before using with DRerio LogAI

  6. Check baud rate:

    arduino:
  baud_rate: 9600 # Match Arduino sketch

Analysis and Results Issues

Missing output files

Problem: Analysis completes but expected files are missing

Solutions:

  1. Check output directory:

    # Look for <video_name>_results/ directory
ls -la *_results/

  2. Verify analysis completed successfully:

    • Check for error messages in final analysis report
    • Look at logs: logs/zebtrack.log

  3. Check export settings:

    • Wizard Step 5: Ensure desired outputs are enabled
    • "Save Annotated Video", "Generate Heatmap", etc.

  4. Disk space:

    # Check available space
df -h .  # Linux
# or check Properties in Windows

  5. File permissions:

    # Ensure write permissions in output directory
chmod -R u+w *_results/  # Linux

Parquet file is corrupted

Problem: Cannot open Parquet file, "Invalid Parquet file" error

Solutions:

  1. Verify file integrity:

    import pandas as pd
try:
    df = pd.read_parquet("file.parquet")
    print("File is valid")
except Exception as e:
    print(f"Error: {e}")

  2. Check file size:

    ls -lh file.parquet
# Should be >0 bytes
    • If 0 bytes: File was not written (analysis may have crashed)

  3. Try recovery:

    import pyarrow.parquet as pq
table = pq.read_table("file.parquet")
# If successful, re-export
table.to_pandas().to_parquet("file_recovered.parquet")

  4. Fallback to CSV (if available):

    • Change export format to CSV
    • Re-run analysis

Heatmap looks wrong

Problem: Heatmap doesn't match expected movement patterns

Causes and Solutions:

  1. Wrong ROI definition:

    • Verify ROI covers correct area
    • Check arena boundary is correct

  2. Coordinate system issue:

    • If using calibration, verify calibration values
    • Check pixel-to-cm conversion is accurate

  3. Track filtering:

    • Short, erroneous tracks may skew heatmap

    • Filter tracks by minimum duration:

      df = df.groupby('track_id').filter(lambda x: len(x) > 100)  # At least 100 frames

  4. Resolution mismatch:

    • Heatmap resolution should match video resolution
    • Check settings: camera.desired_width, camera.desired_height

Metrics seem incorrect

Problem: Calculated metrics (distance, speed, time in ROI) don't match expectations

Debugging Steps:

  1. Check calibration:

    import pandas as pd
df = pd.read_parquet("3_CoordMovimento_video.parquet")

# If calibrated, x_cm and y_cm columns should exist
print(df.columns)

# Check scale
print(df[['x_cm', 'y_cm']].describe())

  2. Verify ROI definitions:

    • Open 1_ArenaROI_video.parquet
    • Check ROI coordinates match visual expectations

  3. Check for track ID swaps:

    # Count unique track IDs
num_tracks = df['track_id'].nunique()
print(f"Number of unique tracks: {num_tracks}")
# Should match number of subjects (if single subject, should be 1-2)

  4. Manual validation:

    • Watch annotated video alongside metrics
    • Verify at least 1-2 ROI transitions manually
    • Check speed calculations seem reasonable

  5. Re-run analysis:

    • If settings were incorrect, adjust and re-run
    • Save project settings for reproducibility

Application Errors

"Error loading model"

Problem: Application fails to load AI model

Solutions:

  1. Check model path:

    # In config.local.yaml
yolo_model:
  path: "weights/best_seg_lateral.pt" # must exist under weights/

    There is no detector: section, and there never was. The settings model forbids unknown keys, so inventing one makes the whole configuration fail validation and the application exits before opening a window.

  2. Download the models:

    poetry run fetch-weights

    This fetches the project's own trained models and verifies their checksums. Stock Ultralytics weights (yolov8n.pt and friends) are not interchangeable with them: they do not know the aquarium and zebrafish classes.

  3. Verify model format:

    • YOLO: .pt file (PyTorch)
    • OpenVINO: .xml and .bin files

  4. Check model compatibility:

    • Ensure model is for object detection (not classification or segmentation)
    • Verify model input size matches expectations

  5. Try default model:

    • Remove custom model path from config
    • Run poetry run fetch-weights to restore the published set

"Permission denied" errors

Problem: Cannot save files or access directories

Solutions:

Windows

  1. Run as Administrator (right-click → Run as Administrator)
  2. Check folder permissions (Properties → Security)
  3. Disable "Controlled folder access" (Windows Security → Virus & threat protection → Ransomware protection)

Linux

  1. Check file ownership:

    ls -la /path/to/file

  2. Fix ownership if needed:

    sudo chown -R $USER:$USER /path/to/directory

  3. Fix permissions:

    chmod -R u+rw /path/to/directory

"Configuration file not found"

Problem: Application cannot find config.yaml

Solutions:

  1. Ensure in correct directory:

    pwd  # Should be DRerio-LogAI root directory
ls config.yaml  # Should exist

  2. Create default config:

    # Config should be created automatically
# If missing, copy from repository
cp config.yaml.example config.yaml

  3. Specify config path:

    poetry run zebtrack --config /path/to/config.yaml

Application won't start (immediate crash)

Problem: Application crashes immediately on launch

Debugging:

  1. Check Python version:

    poetry run python -V  # Must be 3.12.x or 3.13.x

  2. Run with verbose logging:

    poetry run zebtrack --verbose --debug

  3. Check logs:

    cat logs/zebtrack.log
# Look for last ERROR message

  4. Test imports:

    poetry run python -c "import zebtrack; print('Success')"

  5. Verify dependencies:

    poetry check  # Verify lock file
poetry show   # List installed packages

  6. Clean reinstall:

    rm -rf .venv
rm poetry.lock
poetry install

Configuration Issues

Settings are not being saved

Problem: Changes in settings dialog don't persist

Solutions:

  1. Check for config.local.yaml:

    ls -la config.local.yaml
# If exists, settings are saved here

  2. Verify write permissions:

    # Should be writable
ls -la config*.yaml

  3. Check for syntax errors:

    # Validate YAML syntax
poetry run python -c "import yaml; yaml.safe_load(open('config.local.yaml'))"

  4. Manual edit:

    • Open config.local.yaml in text editor
    • Verify structure matches config.yaml
    • Check indentation (use spaces, not tabs)

Configuration changes have no effect

Problem: Modified settings don't change application behavior

Solutions:

  1. Ensure editing correct file:

    • config.yaml: Default settings (overridden by local)
    • config.local.yaml: Local overrides (takes precedence)

  2. Restart application:

    • Settings are loaded at startup
    • Fully close and reopen application

  3. Check setting path:

    # Correct structure
camera:
  index: 0

# Incorrect (no effect)
camera_index: 0

  4. Verify no typos:

    • Pydantic validation will reject unknown settings
    • Check logs for validation errors

  5. Test with minimal config:

    # Temporarily rename config.local.yaml
mv config.local.yaml config.local.yaml.bak

# Restart application (uses defaults)
poetry run zebtrack

# If works, issue is in local config

Getting More Help

Reporting Bugs

When reporting bugs, include:

  1. System information:

    • OS and version
    • Python version (python --version)
    • GPU model (if applicable)

  2. Application version:

    poetry run zebtrack --version

  3. Error logs:

    cat logs/zebtrack.log  # Last 50 lines

  4. Steps to reproduce:

    • Exact sequence of actions
    • Sample video (if possible)
    • Configuration files

  5. Expected vs actual behavior

Community Support

Documentation

Last Updated: November 2025 Version: 2.1

Clone this wiki locally