Skip to content

Troubleshooting Guide

Common issues and solutions for the WildDetect monorepo.

Installation Issues

uv command not found

Solution: 

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

ImportError after installation

Solution: 

# Ensure virtual environment is activated
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/macOS

# Reinstall in development mode
cd wildetect
uv pip install -e .

GPU and CUDA Issues

CUDA out of memory

Solutions: 1. Reduce batch size: 

processing:
  batch_size: 16  # Reduce from 32

  1. Reduce tile size: 

    processing:
  tile_size: 640  # Reduce from 800

  2. Clear GPU cache: 

    import torch
torch.cuda.empty_cache()

GPU not detected

Check CUDA: 

import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
print(f"GPU: {torch.cuda.get_device_name(0)}")

Solutions: 1. Reinstall PyTorch with CUDA: 

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

  1. Set device explicitly: 
    model:
  device: "cuda:0"

Windows-Specific Issues

ProcessPool not supported

Issue: ProcessPoolExecutor doesn't work on Windows

Solution: Package automatically uses ThreadPoolExecutor on Windows

Path issues

Use forward slashes or raw strings: 

# Good
path = "D:/data/images"
path = r"D:\data\images"

# Bad
path = "D:\data\images"  # Backslashes can cause issues

MLflow Issues

Can't connect to MLflow server

Solutions: 1. Start MLflow server: 

scripts\launch_mlflow.bat

  1. Check environment variable: 

    echo %MLFLOW_TRACKING_URI%
# Should be: http://localhost:5000

  2. Set in .env: 

    MLFLOW_TRACKING_URI=http://localhost:5000

Model not found in registry

Solutions: 1. List available models: 

mlflow models list

  1. Check model name and alias: 
    model:
  mlflow_model_name: "detector"  # Check this is correct
  mlflow_model_alias: "production"  # or version number

Data Loading Issues

Images not found

Solutions: 1. Use absolute paths 2. Check file extensions match 3. Verify directory structure

Annotation format errors

Solutions: 1. Validate COCO format: 

from wildata.validation import validate_coco
errors = validate_coco("annotations.json")

  1. Check bbox coordinates
  2. Verify image IDs match

Performance Issues

Detection is slow

Solutions: 1. Use GPU if available 2. Increase batch size 3. Use multithreaded pipeline: 

processing:
  pipeline_type: "multithreaded"
  num_data_workers: 4

High memory usage

Solutions: 1. Enable streaming mode (WilData): 

processing_mode: "streaming"

  1. Process in smaller batches
  2. Clear cache between batches

DVC Issues

DVC push fails

Solutions: 1. Check remote configuration: 

dvc remote list

  1. Verify credentials: 

    dvc remote modify myremote access_key_id YOUR_KEY

  2. Test connection: 

    dvc remote list
dvc status

Label Studio Integration

Can't connect to Label Studio

Solutions: 1. Start Label Studio: 

scripts\launch_labelstudio.bat

  1. Check API key in .env: 
    LABEL_STUDIO_API_KEY=your_key
LABEL_STUDIO_URL=http://localhost:8080

FiftyOne Issues

FiftyOne app won't launch

Solutions: 1. Check FiftyOne installation: 

uv pip install fiftyone

  1. Clear FiftyOne database: 

    fiftyone app config database_dir

  2. Use different port: 

    fiftyone app launch --port 5152

Common Error Messages

"No module named 'wildetect'"

Solution: Install in development mode: 

cd wildetect
uv pip install -e .

"Permission denied"

Solution: Run as administrator or fix permissions: 

icacls "D:\data" /grant %USERNAME%:F /t

"Port already in use"

Solution: Kill process using port: 

# Find process
netstat -ano | findstr :5000

# Kill process (replace PID)
taskkill /PID <PID> /F

Getting Help

  1. Check logs: Look in logs/ directory
  2. Enable verbose mode: Add --verbose flag
  3. GitHub Issues: Report bugs
  4. Discussions: Ask questions in GitHub Discussions

Debug Mode

Enable debug logging:

logging:
  log_level: "DEBUG"
  verbose: true

Or in Python:

import logging
logging.basicConfig(level=logging.DEBUG)

Still having issues? Open an issue on GitHub with: - Error message - System info (wildetect info) - Steps to reproduce - Relevant configuration files