Troubleshooting Guide

Common issues and solutions for Custom Excel Template Import.

Template Configuration Issues

Template Creation Problems

Excel File Not Uploading

Symptoms: Upload fails or file not recognized Solutions:

Ensure file is in .xlsx format (not .xls or .csv)
Check file size (large files may timeout)
Verify file is not corrupted or password-protected
Remove any macros or VBA code from the file

Columns Not Detected

Symptoms: Expected columns don't appear in mapping interface Solutions:

Verify column headers are in the first row
Remove merged cells in header row
Check for hidden columns or sheets
Ensure column headers have text (not formulas)

Sheet Not Found

Symptoms: Expected sheets don't appear in configuration Solutions:

Check sheet names for special characters
Ensure sheets contain data (empty sheets may be ignored)
Verify sheet visibility (unhide if necessary)
Remove completely empty sheets

Column Mapping Issues

Required Field Validation Errors

Symptoms: Template validation fails due to missing required fields Solutions:

Map all fields marked with red "Required" badges
Use the System Fields reference to find correct field names
Check that mapped columns contain actual data
Verify field compatibility (dates to date fields, numbers to amount fields)

System Field Not Available

Symptoms: Expected field doesn't appear in dropdown Solutions:

Use the search function in field dropdowns
Check correct field category (header vs line)
Verify sheet type is set correctly
Some fields may only be available for specific import modes

Mapping Not Saved

Symptoms: Mappings reset after configuration Solutions:

Click "Save" button after making changes
Ensure stable internet connection during save
Check browser console for JavaScript errors
Try refreshing page and reconfiguring

Import Processing Issues

Data Import Failures

Invoice Creation Errors

Symptoms: Import process fails with validation errors Solutions:

Check LHDN field requirements are met
Verify tax calculations are correct
Ensure required customer information is complete
Review date formats (use proper Excel date formatting)

Calculation Errors

Symptoms: Totals don't match or are incorrect Solutions:

Verify Excel formulas are calculated before import
Check for circular references in Excel file
Ensure number formatting is consistent
Review tax rate applications and defaults

Linking Issues (Standard Mode)

Symptoms: Header and line data not properly linked Solutions:

Verify Invoice ID field exists in both sheets
Check Invoice ID values match exactly (case-sensitive)
Remove extra spaces or formatting from Invoice IDs
Ensure Invoice ID column is mapped in both sheets

Code Mapping Problems

Values Not Transformed

Symptoms: Excel values appear unchanged in final invoices Solutions:

Verify exact spelling in code mappings (case-sensitive)
Check for extra spaces or hidden characters
Ensure code mapping is saved correctly
Test with simplified values first

Invalid Code Errors

Symptoms: Transformed codes cause validation errors Solutions:

Verify system values match LHDN requirements exactly
Check code format specifications in LHDN documentation
Use standard codes from LHDN reference lists
Test codes with LHDN validation tools

Missing Code Mappings

Symptoms: Some Excel values don't have corresponding mappings Solutions:

Review import logs to identify unmapped values
Add mappings for all possible Excel values
Consider using conditional defaults for edge cases
Implement data cleaning in Excel before import

Default Value Issues

Defaults Not Applied

Symptoms: Expected default values don't appear in imported invoices Solutions:

Check condition syntax and field names
Verify target field selection is correct
Test conditions with actual Excel data
Ensure default value format matches field requirements

Conditional Logic Errors

Symptoms: Wrong defaults applied or conditions not matching Solutions:

Review condition order (first match wins)
Check operator selection (equals vs contains)
Verify case sensitivity in text comparisons
Test with simplified conditions first

Performance Issues with Defaults

Symptoms: Import process very slow with many defaults Solutions:

Simplify complex text matching conditions
Use exact matches instead of contains when possible
Reduce number of conditional rules where feasible
Consider data pre-processing in Excel

Performance and Scale Issues

Large File Processing

Timeout Errors

Symptoms: Import process times out for large files Solutions:

Split large files into smaller batches
Remove unnecessary columns and rows
Optimize Excel file (remove unused formatting)
Process during off-peak hours

Memory Errors

Symptoms: System runs out of memory during processing Solutions:

Reduce file size by removing unused data
Process files in smaller chunks
Close other applications during import
Contact support for system resource limits

Slow Processing

Symptoms: Import takes very long time to complete Solutions:

Optimize Excel file structure
Reduce complex conditional logic
Remove excessive formatting from Excel
Use simpler import modes when possible

Data Quality Issues

Validation Failures

LHDN Compliance Errors

Symptoms: Final invoices fail LHDN validation Solutions:

Review LHDN field requirements carefully
Use strict validation mode during testing
Verify all required fields are populated
Check tax calculations and classifications

Business Rule Violations

Symptoms: Data violates business logic rules Solutions:

Review template validation messages
Check field value ranges and formats
Verify customer and product data integrity
Ensure date logic is consistent

Currency and Tax Issues

Symptoms: Currency or tax calculations are incorrect Solutions:

Verify exchange rate mappings and defaults
Check tax code mappings against LHDN standards
Ensure consistent currency codes throughout
Review tax-exempt and zero-rate scenarios

User Interface Issues

Display Problems

Dark Mode Issues

Symptoms: Interface elements not visible in dark mode Solutions:

Switch to light mode temporarily
Clear browser cache and refresh
Update browser to latest version
Report UI issues for fixing

Mobile/Responsive Issues

Symptoms: Interface doesn't work properly on mobile devices Solutions:

Use desktop browser for template configuration
Rotate device to landscape orientation
Zoom out to see more interface elements
Switch to desktop for complex operations

Performance Issues in Browser

Symptoms: Interface is slow or unresponsive Solutions:

Close other browser tabs and applications
Clear browser cache and cookies
Disable browser extensions temporarily
Try different browser (Chrome, Firefox, Safari)

Getting Help

Self-Service Resources

Template Validation: Use built-in validation to identify issues
Sample Data: Test with small, known-good data sets
Documentation: Review relevant sections of this guide
Error Messages: Read error messages carefully for specific guidance

Escalation Process

Gather Information: Collect error messages, template settings, and sample data
Document Steps: Note exact steps that led to the issue
Test Isolation: Try to reproduce with minimal data
Contact Support: Provide detailed information for faster resolution

Information to Provide

Template name and configuration
Excel file structure and sample data
Error messages (exact text)
Browser and operating system details
Steps to reproduce the issue

Prevention Best Practices

Template Design

Start with simple configurations and add complexity gradually
Test thoroughly with sample data before production use
Document template logic and business rules
Regular review and maintenance of templates

Data Preparation

Standardize Excel file formats across your organization
Implement data validation in source systems
Clean data before export to Excel
Maintain consistent naming conventions

Process Management

Establish testing procedures for new templates
Train users on proper Excel file preparation
Monitor import success rates and error patterns
Regular backup of working template configurations

Ongoing Maintenance

Review and update code mappings regularly
Monitor for new Excel data patterns
Update default values as business rules change
Performance monitoring and optimization

Troubleshooting