# Common Errors and Troubleshooting

**Quick reference for fixing common issues. For error handling patterns when writing code, see `error_handling.md`.**

## Data Loading Errors

### Error: "Data file not found"
**Cause:** DATA_FILE path in config.py is incorrect
**Fix:**
1. Check that your CSV file exists
2. Update `DATA_FILE` in config.py with correct filename
3. If file is in a subdirectory, set `DATA_DIR` in config.py

### Error: "Required column 'USD' not found"
**Cause:** Column name in data doesn't match config
**Fix:**
1. Check your CSV column names
2. Update `REVENUE_COLUMN` in config.py to match your data
3. Update other column mappings (DATE_COLUMN, CUSTOMER_COLUMN, etc.)

### Error: "All InvoiceDate values are NaN"
**Cause:** Date column parsing failed
**Fix:**
1. Check date format in your CSV
2. Add fallback date columns to `DATE_FALLBACK_COLUMNS` in config.py
3. Ensure at least one date column exists (Month, Year, etc.)

## Analysis Errors

### Error: "DataFrame is empty" after filtering
**Cause:** Date range or year filters too restrictive
**Fix:**
1. Check `MIN_YEAR` and `MAX_DATE` in config.py
2. Check `ANALYSIS_YEARS` includes years in your data
3. Verify date parsing worked (check data_loader output)

### Error: Charts show scientific notation (1e8)
**Cause:** Forgot to divide by 1e6 before plotting
**Fix:**
```python
# WRONG:
ax.plot(revenue, ...)

# CORRECT:
ax.plot(revenue / 1e6, ...)
setup_revenue_chart(ax)
```

### Error: "Year column has mixed types"
**Cause:** LTM year is string "2025 (LTM 9/2025)" while others are int
**Fix:**
```python
from analysis_utils import sort_mixed_years
df_sorted = sort_mixed_years(df, year_col='Year')
```

## Configuration Errors

### Error: LTM not working correctly
**Cause:** LTM configuration incorrect
**Fix:**
1. Check `LTM_ENABLED = True` in config.py
2. Verify `LTM_START_MONTH`, `LTM_START_YEAR`, `LTM_END_MONTH`, `LTM_END_YEAR`
3. Ensure dates are within your data range

### Error: Exclusion filters not working
**Cause:** Filter configuration incorrect
**Fix:**
1. Check `EXCLUSION_FILTERS['enabled'] = True`
2. Verify `exclude_by_column` matches a column in your data
3. Check `exclude_values` list is correct

## Import Errors

### Error: "No module named 'config'"
**Cause:** Running script from wrong directory
**Fix:**
1. Run scripts from template root directory
2. Or add template directory to Python path

### Error: "No module named 'data_loader'"
**Cause:** Missing import or wrong directory
**Fix:**
1. Ensure all template files are in the same directory
2. Check import statements match file names

## Best Practices to Avoid Errors

1. **Always use utilities:** Use `analysis_utils.py` functions instead of manual code
2. **Validate data:** Run `validate_data_structure()` after loading
3. **Check config:** Verify all column names match your data (use `config_validator.py`)
4. **Test incrementally:** Test data loading before running full analysis
5. **Read error messages:** They usually tell you exactly what's wrong
6. **Use Cursor AI:** Ask AI to fix errors - it knows template patterns

## Using Cursor AI to Fix Errors

When you encounter an error, ask Cursor AI:
```
"Fix this error: [paste error message]"
```

The AI will:
- ✅ Understand the error context
- ✅ Reference template patterns
- ✅ Suggest specific fixes
- ✅ Use template utilities correctly

**See also:** `.cursor/rules/error_handling.md` for how to write error messages that help AI fix issues.