sales-data-analysis/.cursor/rules/common_errors.md

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:

# 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:

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.