Common Issues & Solutions¶

Quick solutions for common problems.

Installation Issues¶

"pip: command not found"¶

Problem: pip not installed or not in PATH

Solution 1: Use Python module syntax

python -m pip install iovalence

Solution 2: Add pip to PATH - Windows: Control Panel → System → Environment Variables - macOS/Linux: Update PATH in ~/.bash_profile

"No module named iovalence"¶

Problem: IOValence not installed or wrong environment

Solutions:

# Verify installation
iovalence --version

# Reinstall
pip install --upgrade --force-reinstall iovalence

# Check virtual environment
which python  # Should show your venv

Configuration Issues¶

"Config value 'plugins': The "minify" plugin is not installed"¶

Problem: minify plugin referenced but not installed

Solutions:

Option 1 - Install the plugin:

pip install mkdocs-minify-plugin

Option 2 - Remove from config (if not needed):

# In mkdocs.yml, remove:
plugins:
  - minify

Data Issues¶

"CSV parse error"¶

Problem: CSV format not recognized

Check:

# Verify file encoding
file data.csv  # Should show UTF-8

# Check headers
head -n 1 data.csv  # First line should be headers

# Validate CSV format
python -c "import csv; csv.reader(open('data.csv'))"

Solution: Ensure CSV is: - UTF-8 encoded - Has proper headers - No special characters in column names - Consistent field count

"Missing values in data"¶

Problem: Empty cells in dataset

Solution:

import pandas as pd

# Load data
df = pd.read_csv('data.csv')

# Remove rows with missing values
df = df.dropna()

# Or fill missing values
df = df.fillna(df.mean())  # Numeric columns
df = df.fillna('unknown')  # Text columns

# Save cleaned data
df.to_csv('data_cleaned.csv', index=False)

Training Issues¶

"Out of memory error"¶

Problem: Not enough RAM for training

Solutions:

# Reduce batch size
training:
  batch_size: 16  # Instead of 64

# Use gradient accumulation
  gradient_accumulation_steps: 4

# Reduce model size
  layers: [64, 32]  # Smaller network

"Training stuck / not improving"¶

Problem: Model isn't learning

Solutions:

# Check learning rate
training:
  learning_rate: 0.01  # Try higher

# Check data quality
  # Verify: balanced data, no duplicates, correct labels

# Try different optimizer
  optimizer: adam

# More epochs
  epochs: 50

"NaN (Not a Number) loss"¶

Problem: Exploding gradients or bad data

Solutions:

# Reduce learning rate
training:
  learning_rate: 0.0001

# Add gradient clipping
  gradient_clip: 1.0

# Check data
  # Remove outliers, scale values to [0, 1]

"Model too large, won't fit on disk"¶

Problem: Saved model exceeds available space

Solution:

# Compress model
iovalence compress --model model.pkl --output model_compressed.pkl

# Or use model quantization
iovalence quantize --model model.pkl --bits 8

Performance Issues¶

"Training very slow"¶

Check & Solutions:

# Check if GPU is available
iovalence check --gpu

# If GPU available but not used:
# Install CUDA support
pip install iovalence[gpu]

# If no GPU:
# Reduce batch size for faster iterations
# Use model quantization
iovalence quantize --model model.pkl

"Poor prediction accuracy"¶

Diagnostic Steps:

Check data quality
```
iovalence diagnose --data train.csv
```

Review metrics

iovalence evaluate --model model.pkl --test test.csv

Check confusion matrix
Which classes are confused?
Are they actually similar?
Get more data
Accuracy ∝ data quality & quantity
Collect 2-10x more examples

Adjust model

training:
  epochs: 50        # More training
  learning_rate: 0.001  # Lower learning rate
  dropout: 0.2      # Slight regularization

Deployment Issues¶

"Agent fails in production"¶

Check: - ✅ Same Python version - ✅ All dependencies installed - ✅ Model file readable - ✅ Data preprocessing same as training - ✅ Input format matches training

"Predictions differ from training"¶

Cause: Data preprocessing differences

Solution: Ensure identical preprocessing:

# In config - must match training exactly
data:
  preprocessing:
    - lowercase: true
    - remove_special_chars: true
    - tokenize: true

Common Error Messages¶

Error	Cause	Solution
`ModuleNotFoundError: No module named 'torch'`	PyTorch not installed	`pip install torch`
`CUDA out of memory`	GPU memory exceeded	Reduce batch_size
`ValueError: shapes not aligned`	Data shape mismatch	Check data dimensions
`RuntimeError: CUDA device not found`	GPU not available	Check NVIDIA drivers
`KeyError: 'column_name'`	Column not in CSV	Check header names

Diagnostic Commands¶

Check System¶

iovalence check

Output shows: - ✓ IOValence installed - ✓ Python version - ✓ Dependencies OK - ✓ GPU available

Check Data¶

iovalence diagnose --data train.csv

Shows: - Data shape - Missing values - Class distribution - Data types

Check Model¶

iovalence validate --model model.pkl

Shows: - Model architecture - Parameter count - Input/output shapes - Training metrics

Getting More Help¶

Enable Debug Mode¶

iovalence --debug train

Shows detailed logging for troubleshooting

Check Logs¶

tail -f ~/.iovalence/logs/latest.log

Visit Documentation¶

FAQ - Frequently asked questions
Debug Guide - Debugging strategies
Support - Get professional help

Preventing Issues¶

Best Practices¶

Always use virtual environment

python -m venv iovalence-env
source iovalence-env/bin/activate  # Linux/macOS

Validate data before training
```
iovalence diagnose --data train.csv
```

Start with small model

# Begin with simple architecture
layers: [64, 32]
# Increase only if needed

Monitor metrics during training
```
iovalence train --verbose
```

Save checkpoints

training:
  save_checkpoint: true
  checkpoint_interval: 5

Still stuck? Contact Support or Check FAQ