This article helps you identify and resolve errors that may occur when using the bulk product mapping feature with ServiceTitan. If you encounter an error during the import process, use this guide to find the solution.
Understanding Error Messages
When you import your Excel file, the system will validate your data and display any errors in the preview step. Error messages will also be included in the email notification you receive after import.
Result Types:
Error: The row cannot be processed. You must fix the issue and re-import.
Duplicate: The row is identical to another entry in the file or an existing mapping.
Skipped: No changes needed (mapping already exists with same values, or both ServiceTitan fields are empty).
Created/Updated: Mapping was successfully created or updated.
File Format Errors
These errors prevent the entire import from proceeding. You must fix the file before trying again.
Error Message | Why This Happens | How to Solve |
"Please select a valid Excel file." | File is corrupted or not an Excel file | 1. Re-export a fresh file from ArcSite |
Ensure file has
.xlsxextensionDon't open file in other programs while uploading | | "The import does not support older versions of the Excel format. Please save as .xlsx and try again." | File is saved as
.xls(old Excel format) | 1. Open the file in ExcelClick File > Save As
Choose Excel Workbook (.xlsx) format
Save and re-import | | "Excel file does not contain any worksheets" | Workbook is empty or all sheets deleted | 1. Re-export a fresh file from ArcSite
Don't delete any worksheets from the exported file | | "Excel file does not contain headers" | Header row (row 2) is missing | 1. Re-export a fresh file from ArcSite
Don't delete or modify row 2 (the header row) | | "A required column is missing. This spreadsheet cannot be uploaded." | One or more required columns were deleted or renamed | 1. Re-export a fresh file from ArcSite
Don't delete, rename, or reorder any columns
Required columns are: • Product ID • Product Name • Category Name • ServiceTitan Product Type • ServiceTitan Product ID |
Data Validation Errors
These errors affect individual rows. The import will continue, but rows with errors won't be processed.
Error Message | Why This Happens | How to Solve |
"ServiceTitan Product Item Type and ID are required together" | You filled in ServiceTitan Product Type but not Product ID (or vice versa) | Fill in both fields: |
ServiceTitan Product Type (Material or Service)
ServiceTitan Product ID (the Item Code)Or leave both empty if you don't want to map this product | | "Invalid Product Type '{type}'. Must be one of: {valid_types}" | ServiceTitan Product Type contains invalid text | Use only these values: • Material (for Material Items) • Service (for Service Items) Copy the exact spelling (case-sensitive) | | "Product Name mismatch: Excel has '{excel_name}', but database has '{db_name}'" | Product Name in Excel doesn't match what's in ArcSite | 1. Don't modify the Product Name column
Re-export a fresh file to get correct names
Copy your ServiceTitan data into the new file | | "Category Name mismatch: Excel has '{excel_category}', but database has '{db_category}'" | Category Name in Excel doesn't match what's in ArcSite | 1. Don't modify the Category Name column
Re-export a fresh file to get correct categories
Copy your ServiceTitan data into the new file |
Product Identification Errors
These errors affect individual rows. The import will continue, but rows with errors won't be processed.
Error Message | Why This Happens | How to Solve |
"Product ID is required and must be in 'id:xxxx' format" | Product ID is missing, empty, or in wrong format | 1. Don't modify the Product ID column |
Re-export a fresh file from ArcSite
Product IDs should look like:
id:1234Copy your ServiceTitan data into the new file | | "Product ID: {product_id} is not found." | Product ID doesn't exist in your ArcSite account | 1. The product may have been deleted from ArcSite
Re-export a fresh file to get current products
Remove this row if the product no longer exists |
Duplicate Detection Errors
These rows are marked as duplicates and will be skipped during import.
Error Message | Why This Happens | How to Solve |
"Duplicate Row: Product ID {product_id} already exists" | The same Product ID appears multiple times in your Excel file | 1. Find all rows with this Product ID |
Keep only one row per Product ID
Delete the duplicate rows4. Re-import the file | | "Duplicate Row: ServiceTitan Item ID {st_id} and Type {st_type} already exists" | The same ServiceTitan Product ID + Type combination appears multiple times | 1. Find all rows with this ServiceTitan ID and Type
Decide which ArcSite product should map to this ServiceTitan item
Remove the duplicate mappings4. Re-import the file |
ServiceTitan Connection Errors
These errors indicate issues with ServiceTitan data or connectivity.
Error Message | Why This Happens | How to Solve |
"ServiceTitan Pricebook Item ID: {st_id} not found with type {st_type}." | The ServiceTitan Product ID doesn't exist in your ServiceTitan pricebook | 1. Log in to ServiceTitan |
Go to Settings > Pricebook
Verify the Item Code exists
Check for typos or extra spaces
Ensure you selected the correct Product Type (Material vs Service)
Update the Excel file with the correct information | | "ServiceTitan API Error: failed to validate item ID {st_id} with type {st_type}." | ServiceTitan couldn't verify the item due to a connection issue | 1. Wait a few minutes and try importing again
Check that your ServiceTitan integration is active:• Go to Settings > Integrations > Apps• Verify ServiceTitan shows as "Connected"
If still failing, contact ArcSite support | | "ServiceTitan integration not configured for this organization" | ServiceTitan integration is not set up or was disconnected | 1. Go to Settings > Integrations > Apps
Find ServiceTitan and click "Connect"
Follow the connection setup steps
See the ArcSite + ServiceTitan article for detailed instructions |
Common Issues and Quick Fixes
❌File import fails: Make sure your file is saved as
.xlsx(not.xlsor.csv), contains all required columns, and isn’t open in another program during upload.❌Product not mapping: Double-check that both ServiceTitan Product Type and ID fields are filled in for every product you want to map.
❌Error message in preview: Download the error report, fix issues indicated, and re-import only the corrected rows.
Best Practices
✅ Only edit the ServiceTitan Product Type and ID columns in the Excel file.
✅ Always export the latest template from ArcSite before making changes.
✅ Test with a small batch before doing a large import.
✅ Double-check Item Codes for accuracy before importing.