110 lines
3.4 KiB
Markdown
110 lines
3.4 KiB
Markdown
# 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.
|