Troubleshooting Guide

Common issues and how to fix them.

Installation Issues

"Command not found: crml"

Problem: After installing, crml command doesn't work.

Solutions:

Check if Python's bin directory is in PATH:

# Find where crml was installed
pip show crml-lang

# Add to PATH (macOS/Linux)
export PATH="$PATH:$HOME/.local/bin"

# Add to PATH (Windows)
set PATH=%PATH%;%APPDATA%\Python\Scripts

Use Python module directly:
```
python -m crml.cli --help
```
Reinstall with user flag:
```
pip install --user crml-lang
```

"No module named 'crml'"

Problem: Python can't find the CRML module.

Solutions:

Check installation:
```
pip list | grep crml
```

Install in correct environment:

# If using virtual environment
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install crml-lang

Check Python version:
```
python --version  # Must be 3.8+
```

Validation Errors

"Invalid YAML syntax"

Problem: YAML file won't parse.

Common causes:

Tabs instead of spaces:

# ❌ Wrong (tabs)
model:
 frequency:

# ✅ Correct (spaces)
model:
  frequency:

Inconsistent indentation:

# ❌ Wrong
model:
  frequency:
    model: poisson
   parameters:  # Should be 4 spaces

# ✅ Correct
model:
  frequency:
    model: poisson
    parameters:

Missing quotes:

# ❌ Wrong
meta:
  name: my-model  # Hyphen needs quotes

# ✅ Correct
meta:
  name: "my-model"

Fix: Use the validator to see exact error:

crml validate model.yaml

"Missing required field"

Problem: Model is missing required parameters.

Required fields:

crml: "1.1"  # Version (required)

model:  # Model section (required)
  frequency:  # Frequency model (required)
    model: poisson  # Model type (required)
    parameters:  # Parameters (required)
      lambda: 0.05  # Lambda value (required for Poisson)

  severity:  # Severity model (required)
    model: lognormal  # Model type (required)
    parameters:  # Parameters (required)
      mu: 11.5  # Mu value (required for Lognormal)
      sigma: 1.2  # Sigma value (required for Lognormal)

"Invalid parameter value"

Problem: Parameter is out of valid range.

Common issues:

Negative lambda:

# ❌ Wrong
lambda: -0.05

# ✅ Correct
lambda: 0.05  # Must be positive

Sigma too small:

# ❌ Wrong
sigma: 0  # Must be > 0

# ✅ Correct
sigma: 0.5  # Positive value

Lambda > 1 for Poisson:

# ⚠️ Warning: lambda > 1 means >100% probability
lambda: 1.5  # Probably wrong

# ✅ Correct
lambda: 0.15  # 15% probability

Simulation Issues

Results seem unrealistic

Problem: EAL or VaR values don't match expectations.

Debug steps:

Check lambda interpretation:

# Lambda is probability PER ASSET PER YEAR
assets:
  cardinality: 100
frequency:
  lambda: 0.10  # 10% per asset = ~10 events/year total

Verify mu calculation:

# Mu is ln(median_loss)
import math
median_loss = 100000  # $100K
mu = math.log(median_loss)  # 11.51

Check units:
All losses in dollars
All frequencies per year
Cardinality = number of assets

Test with known example:

# Use a validated example
crml simulate spec/examples/data-breach-simple.yaml

"Simulation takes too long"

Problem: Simulation runs for minutes.

Solutions:

Reduce runs temporarily:

crml simulate model.yaml --runs 1000  # Instead of 10000

Check cardinality:

# ❌ Too high
assets:
  cardinality: 1000000  # 1 million assets

# ✅ Reasonable
assets:
  cardinality: 1000  # 1 thousand assets

Use JSON output (faster):

crml simulate model.yaml --format json > results.json

Profile the model:

time crml simulate model.yaml --runs 1000

"Memory error"

Problem: Simulation crashes with out-of-memory error.

Solutions:

Reduce runs:
```
crml simulate model.yaml --runs 5000
```

Reduce cardinality:

assets:
  cardinality: 100  # Instead of 100000

Use streaming mode (if available):
```
crml simulate model.yaml --stream
```

Web Platform Issues

"Cannot connect to localhost:3000"

Problem: Web platform won't load.

Solutions:

Check if server is running:
```
cd web
npm run dev
```

Check port availability:

# Kill process on port 3000
lsof -ti:3000 | xargs kill  # macOS/Linux

Use different port:
```
PORT=3001 npm run dev
```

"API simulation fails"

Problem: Simulation page returns error.

Solutions:

Check Python is available:
```
which python3
python3 --version
```
Install CRML package:
```
pip install crml-lang
```

Check API logs:

# In web terminal, look for errors
POST /api/simulate 500

Test Python directly:

python3 -m crml.cli simulate spec/examples/data-breach-simple.yaml

Parameter Selection Issues

"Don't know what lambda to use"

Problem: Unsure about frequency parameter.

Solutions:

Use industry data:
Verizon DBIR: ~5% for data breaches
Sophos: ~8% for ransomware
KnowBe4: ~10-15% for phishing

Start conservative:

frequency:
  lambda: 0.05  # 5% - conservative estimate

Use expert judgment:
Ask your security team
Review past incidents
Start low, adjust up
See parameter guide:
Understanding Parameters
Writing CRML

"Don't know what mu to use"

Problem: Unsure about severity parameter.

Solutions:

Calculate from median loss:

import math
median_loss = 100000  # $100K
mu = math.log(median_loss)  # 11.51

Use industry benchmarks:
IBM: $100K median for data breach → mu = 11.5
Coveware: $700K for ransomware → mu = 13.5
Use cheat sheet: | Median Loss | Mu Value | |-------------|----------| | $10K | 9.2 | | $50K | 10.8 | | $100K | 11.5 | | $500K | 13.1 | | $1M | 13.8 |

Output Interpretation Issues

"What does VaR mean?"

Problem: Don't understand output metrics.

Explanations:

EAL (Expected Annual Loss): - Average loss per year - Use for budgeting - Example: EAL = $200K → budget $200K/year

VaR 95% (Value at Risk): - 95% of years will be below this - Only 1 in 20 years exceeds - Use for normal worst-case planning

VaR 99%: - 99% of years below this - 1 in 100 years exceeds - Use for stress testing

VaR 99.9%: - Extreme worst-case - 1 in 1000 years - Use for catastrophic planning

"Results vary each time"

Problem: Running simulation multiple times gives different results.

This is normal! Monte Carlo simulation is random.

Solutions:

Use more runs for stability:
```
crml simulate model.yaml --runs 100000
```
Use random seed for reproducibility:
```
crml simulate model.yaml --seed 42
```
Focus on ranges, not exact values:
EAL should be within ~5% each run
If variance is high, increase runs

Integration Issues

"Can't export to JSON"

Problem: JSON export fails or is malformed.

Solutions:

Use correct flag:
```
crml simulate model.yaml --format json
```

Redirect to file:

crml simulate model.yaml --format json > results.json

Validate JSON:
```
cat results.json | python -m json.tool
```

"Python API doesn't work"

Problem: Can't use CRML from Python.

Solutions:

Check import:

try:
    from crml import CRMLModel
    print("Import successful!")
except ImportError as e:
    print(f"Error: {e}")

Check installation:
```
pip show crml-lang
```

Use correct syntax:

from crml.runtime import run_simulation

result = run_simulation("model.yaml", n_runs=10000)
print(result["metrics"]["eal"])

Still Having Issues?

Before asking for help:

✅ Check this troubleshooting guide
✅ Read the FAQ
✅ Try the examples in spec/examples/
✅ Validate your YAML: crml validate model.yaml
✅ Check GitHub issues for similar problems

Get help:

When reporting issues, include:

CRML version: crml --version
Python version: python --version
Operating system
Full error message
Minimal example that reproduces the issue

Example bug report:

CRML Version: 1.1.0
Python: 3.9.7
OS: macOS 12.0

Error: "Invalid YAML syntax"

Steps to reproduce:
1. Create model.yaml with...
2. Run: crml validate model.yaml
3. See error: ...

Expected: Should validate successfully
Actual: Gets syntax error

This helps us fix issues faster!