When preparing CSV files for Housing.Cloud sandbox provisioning, even small formatting issues can cause import errors. This guide walks through the most common CSV errors housing admins encounter, explains what causes them, and provides step-by-step fixes.
Most errors fall into a few categories: formatting problems (dates, commas, special characters), missing or duplicate data, incorrect column names, and structural issues. Once you understand these patterns, troubleshooting becomes straightforward.
Before troubleshooting, always open your CSV in both Excel (or Google Sheets) and a plain text editor like Notepad. The spreadsheet view shows you the data clearly, while the text view reveals hidden formatting issues that spreadsheets mask.
Error: "Missing required field"
What This Means
One or more rows have blank cells in columns marked as required. Housing.Cloud cannot import incomplete records.
How to Find It
The error message usually tells you which row and column has the problem, like "Row 45: sisId is required".
Open your CSV in Excel or Google Sheets
Navigate to the row number mentioned in the error
Look for empty cells in the specified column
How to Fix It
Fill in the missing value. For required fields like sisId, firstName, lastName, or email, you must provide valid data for every student.
If you don't have the data for a particular student, either:
Delete that entire row (if the student shouldn't be included)
Look up the missing information from your SIS or records
Use a placeholder value for sandbox testing (like "Test" for firstName), but note that real data is always better for realistic testing
Preventing This Error
Before saving your CSV, use Excel's filter feature to check for blanks:
Select your data (Ctrl+A or Cmd+A)
Click Data → Filter
Click the dropdown arrow on each required column
Look for "(Blanks)" in the filter menu
If blanks appear, uncheck all items except "(Blanks)" to show only empty cells
Fill in or delete rows with missing data
Error: "Duplicate value in unique field"
What This Means
Two or more rows have the same value in a column that requires unique entries. For example, two students cannot have the same sisId or email address.
Columns That Must Be Unique
sisId (Student Profiles CSV) — Each student must have a unique student ID
email (Student Profiles CSV) — Each student must have a unique email address
accountingCode (Charge Codes CSV) — Each charge must have a unique accounting code
Bed names (Inventory CSV) — Each bed must have a unique name within your inventory
How to Find Duplicates
In Excel:
Select the column that has duplicates (like the sisId column)
Click Data → Filter
Click Data → Sort A to Z
Scroll through the sorted column and look for consecutive identical values
Or use conditional formatting:
Select the column
Click Home → Conditional Formatting → Highlight Cell Rules → Duplicate Values
Excel will highlight all duplicate cells in red
How to Fix It
Determine which record is correct:
If one row has the wrong ID, correct it
If you accidentally entered the same student twice, delete one row
If both records are different students who happen to share an ID or email (which shouldn't happen), investigate your source data—one likely has a typo
For email duplicates, remember that some students may have multiple emails in your SIS. Choose the primary/preferred email for Housing.Cloud.
Error: "Invalid date format"
What This Means
Dates are not formatted as YYYY-MM-DD. Housing.Cloud requires this exact format for all date fields.
Common Date Format Mistakes
Wrong Format | Correct Format |
|---|---|
3/15/2005 | 2005-03-15 |
15-Mar-2005 | 2005-03-15 |
2005/03/15 | 2005-03-15 |
03-15-2005 | 2005-03-15 |
2005-3-5 | 2005-03-05 |
Note that single-digit months and days must include leading zeros (03, not 3).
How to Fix It in Excel
Select the entire date column (click the column letter)
Right-click and choose Format Cells
Select Custom from the Category list
In the Type field, enter: yyyy-mm-dd
Click OK
If dates still look wrong after formatting, Excel may have interpreted them as text. You'll need to re-enter them or use a formula:
In a new column, use:
=TEXT(A2,"yyyy-mm-dd")(assuming your date is in cell A2)Drag the formula down to apply to all rows
Copy the new column and Paste Special → Values back into the original column
Delete the helper column
How to Fix It in Google Sheets
Select the date column
Click Format → Number → Custom number format
Enter: yyyy-mm-dd
Click Apply
Preventing Date Issues
When exporting from your SIS, configure the export to use YYYY-MM-DD format if possible. If your SIS always exports in a different format, you may need to write an Excel formula or script to convert dates after export.
Error: "Invalid column name" or "Unexpected column"
What This Means
Your CSV's column headers don't exactly match the schema. This usually happens because of typos, extra spaces, wrong capitalization, or missing columns.
How to Find It
Compare your CSV's first row (the header row) with the schema document for your CSV type.
Common mistakes:
sisId typed as "sisID" or "SisId" (wrong capitalization)
firstName typed as "first_name" or "FirstName"
dateOfBirth typed as "date of birth" (spaces not allowed)
Extra spaces before or after column names ("sisId " with a trailing space)
How to Fix It
Open your CSV in Excel or Google Sheets
Look at row 1 (the header row)
Compare each column name to the schema
Correct any typos, capitalization errors, or spacing issues
Ensure you haven't added extra columns that aren't in the schema
Column names are case-sensitive. "sisId" is not the same as "sisID" or "SisId". Copy column names exactly from the schema to avoid typos.
Missing Required Columns
If you're missing a required column entirely:
Insert a new column in the correct position (column order doesn't technically matter, but matching the schema order makes troubleshooting easier)
Add the correct header name in row 1
Fill in values for all rows
Error: "Row has too many/too few columns"
What This Means
One or more rows don't have the same number of commas (columns) as the header row. This usually means a cell contains an unescaped comma, or data was copied incorrectly.
How to Find It
Open the CSV in a plain text editor like Notepad. Look for rows that have more or fewer commas than others.
For example, if your header row has 6 commas (7 columns), every data row should also have exactly 6 commas.
Common Causes
Commas in data — A building name like "North Hall, Building A" contains a comma that breaks the CSV structure
Line breaks in data — A cell contains a multi-line address or note that creates unexpected row breaks
Missing trailing columns — A row ends early because the last few columns are blank, and Excel didn't add commas for them
How to Fix It
For commas in data:
Excel and Google Sheets should automatically handle this by wrapping the cell in quotes when you save as CSV. If you're seeing this error, re-save the file to ensure proper quoting:
Open the CSV in Excel
Click File → Save As
Choose CSV (Comma delimited) again
Save over the existing file
For line breaks in data:
Find cells that contain multi-line text (press Ctrl+F and search for line breaks if possible)
Remove line breaks by replacing them with spaces or semicolons
Or remove the multi-line content entirely if it's not needed
For missing trailing columns:
Ensure every row has values or intentional blanks for all columns. In Excel, select the last cell of each row and press Tab to add trailing commas for empty columns.
Error: "Encoding error" or "Unrecognized character"
What This Means
Your CSV contains special characters (like accented letters, curly quotes, or symbols) that weren't saved with the correct encoding. Housing.Cloud expects UTF-8 encoding.
Common Problem Characters
Accented letters: José, Müller, Sofía
Curly quotes or apostrophes: ' ' " " (instead of straight quotes: ' ")
Special symbols: © ® ™ °
Em dashes or en dashes: — – (instead of hyphens: -)
How to Fix It
In Google Sheets (easiest method):
Open your CSV in Google Sheets
Click File → Download → Comma Separated Values (.csv)
Google Sheets automatically uses UTF-8 encoding, which preserves special characters
In Excel (Windows):
Open Excel and go to File → Save As
In the "Save as type" dropdown, look for CSV UTF-8 (Comma delimited)
Select this option instead of the regular "CSV (Comma delimited)"
Save your file
If your version of Excel doesn't have the UTF-8 CSV option, use Google Sheets or a text editor instead.
In a text editor:
Open the CSV in Notepad (Windows) or TextEdit (Mac)
Click File → Save As
In the Encoding dropdown, select UTF-8
Save the file
Preventing Encoding Issues
If your data includes international names or special characters, always save as UTF-8 from the start. Don't copy data from Word documents or websites, as these often introduce curly quotes and other non-standard characters.
Error: "Invalid data type"
What This Means
A column expects numbers but contains text, or expects text but contains numbers. For example, a dollar amount field contains "$3,500.00" instead of "3500.00".
How to Find It
Check columns that should contain numbers (like chargeAmount, capacity, or dollarAmount) for:
Dollar signs: $
Commas: 3,500 should be 3500
Text: "Free" or "N/A" instead of 0
Symbols: %, #, or other characters
Check columns that should contain text (like names or tags) for:
Numbers stored as formulas instead of text
Special formatting that Excel converted to codes
How to Fix It
For number fields:
Select the column
Use Find & Replace (Ctrl+H) to remove unwanted characters:
Find "$" and replace with nothing
Find "," and replace with nothing
Ensure the column is formatted as Number (not Text or Currency)
For text fields:
Select the column
Right-click and choose Format Cells → Text
Re-enter any values that were converted to numbers or dates
Error: "Related record not found"
What This Means
Your CSV references another record that doesn't exist. This happens most often in the Inventory CSV when you reference a parent building or floor that isn't defined, or in the Occupancy CSV when you reference a sisId or bed that doesn't exist.
Common Examples
Inventory CSV: A room row lists "floorName: Floor 2", but no Floor 2 exists in your inventory
Inventory CSV: A floor row lists "buildingName: North Hall", but no North Hall building exists
Occupancy CSV: A residency row lists "sisId: 123456", but that student doesn't exist in your Profiles CSV
Occupancy CSV: A residency row lists "bedName: North-201-A", but that bed doesn't exist in your Inventory CSV
How to Fix It
For Inventory hierarchy issues:
Review your building, floor, room, and bed names
Ensure every floor references a valid buildingName
Ensure every room references a valid floorName
Ensure every bed references a valid roomName
Check for typos in names (extra spaces, capitalization differences)
For Occupancy CSV issues:
Verify that every sisId in your Occupancy CSV exists in your Profiles CSV
Verify that every bedName in your Occupancy CSV exists in your Inventory CSV
Check for exact name matches (case-sensitive, no extra spaces)
Name matching is case-sensitive and space-sensitive. "North Hall" is not the same as "north hall" or "North Hall" (with two spaces). Copy-paste names between CSVs instead of retyping them to avoid mismatches.
Preventing This Error
Build CSVs in the correct order:
Profiles CSV first — Establishes all sisIds
Inventory CSV second — Establishes all building, floor, room, and bed names
Charge Codes CSV third — Establishes accountingCodes
Occupancy CSV last — References sisIds from Profiles and bedNames from Inventory
This way, you can verify that all referenced records exist before creating dependent data.
Error: "File is too large"
What This Means
Your CSV file exceeds the system's upload limit. This rarely happens with sandbox data, but may occur if you're importing thousands of records or accidentally included unnecessary columns with large amounts of text.
How to Fix It
Remove unnecessary columns — Delete any columns that aren't part of the required or optional schema
Trim long text fields — If you have notes or description fields, shorten or remove them
Split into multiple files — Divide your data into two or more CSV files and import them separately (e.g., students A-M in one file, N-Z in another)
File Size Guidelines
Most sandbox CSV files should be small:
Profiles CSV: 100-500 students = ~50 KB to 200 KB
Inventory CSV: 500-2,000 beds = ~100 KB to 500 KB
Charge Codes CSV: 10-50 codes = ~5 KB to 20 KB
If your file is over 1 MB, double-check that you haven't accidentally included thousands of extra rows or large text blocks.
Error: "File not found" or "Upload failed"
What This Means
The file upload didn't complete, or the file path is incorrect. This is usually a browser or network issue, not a problem with your CSV itself.
How to Fix It
Check your internet connection
Try uploading in a different browser (Chrome, Firefox, Edge)
Clear your browser cache and cookies
Disable browser extensions that might interfere with uploads
Try uploading from a different device or network
If the issue persists, contact your Housing.Cloud implementation team and describe the error message you're seeing.
General Troubleshooting Tips
Start Small
If you're having trouble with a large CSV, create a test file with just 5-10 rows of data. This makes it much easier to spot formatting issues and validate that your structure is correct before importing hundreds of records.
Compare to Working Examples
If you've successfully imported one CSV before, use it as a template for future files. Copy the header row and structure, then replace the data rows with your new records.
Use Text View to Debug
Open your CSV in Notepad or TextEdit to see the raw comma-separated format. This reveals hidden characters, encoding issues, and structural problems that spreadsheets hide.
Validate Before Submitting
Before sending CSVs to Housing.Cloud, run through this checklist:
First row is column headers, exactly matching the schema
No blank rows
All required fields have values
Dates are YYYY-MM-DD
Numbers have no formatting ($, commas, etc.)
No duplicate values in unique fields
File extension is .csv
File opens correctly in Excel showing data in columns
Keep Backups
Always save a copy of your working Excel file (.xlsx) with formulas and formatting intact. If something goes wrong with the CSV version, you can regenerate it from your Excel backup without losing work.
Ask for Help
If you're stuck on an error you can't resolve, contact your Housing.Cloud implementation team. Include:
The exact error message
Which CSV file is causing the issue (Profiles, Inventory, etc.)
The row number mentioned in the error (if any)
A sample of your CSV (first 10 rows) so they can see the structure
The implementation team can often spot issues quickly and provide specific guidance for your data.
Related Articles
Working with CSV Files: A Beginner's Guide — Learn CSV basics and formatting rules
Creating Your Student Profiles CSV — Build your student data file
Creating Your Housing Inventory CSV — Build your building and room data file
Creating Your Charge Codes CSV — Build your billing rates file
Preparing Data for Your Sandbox Environment — Overview of the sandbox setup process