Why do I get an unknown error when uploading a Gradebook CSV in Canvas?

Quick Links: | Environment | Solution | Root Cause |

Instructors receive the error message "An unknown error has occurred. Verify the CSV file or try again later" when attempting to upload a Gradebook CSV file into Canvas. This issue commonly occurs when the CSV file includes hidden line breaks within a cell value, particularly in the Notes column. These line breaks do not show up in CSV editors like Excel or Google Sheets but cause Canvas to fail in parsing the file, preventing the upload.

Environment

  • Canvas
  • Gradebook
  • Gradebook CSV Import
  • Files with Notes columns containing line breaks within cell values

Solution

The error message "An unknown error has occurred. Verify the CSV file or try again later" often occurs because of an invalid line break in a Notes column. To fix the error when uploading the Gradebook CSV, follow these steps:

  1. Open the Gradebook CSV file in a CSV editor such as Excel or Google Sheets.
  2. Identify and remove the entire Notes column from the file. Removing this column will not affect existing notes in Canvas, as Canvas will retain the values already saved in the system.
  3. Save the edited file.
  4. Re-upload the CSV file to Canvas.

Now the CSV file should be correctly parsed by Canvas, allowing you to upload the Gradebook without errors. If you are needing to upload the spreadsheet with the Notes column intact (e.g., to update the values in the Notes column), do the following:

  1. Open the Gradebook CSV file in a CSV editor such as Excel or Google Sheets.
  2. Review the Notes column, if included, and check each cell for hidden line breaks. These line breaks may not be immediately visible.
  3. If a line break is found within a cell, remove it by placing the cursor inside the cell and pressing Delete or manually editing the text to eliminate the line break.
  4. Save the edited file.
  5. Re-upload the CSV file to Canvas.

Root Cause

When Canvas attempts to read the Gradebook CSV file, it uses Ruby’s CSV::foreach function, which processes the file line-by-line. This function is known for performing a simple, sequential read of the file and does not robustly handle special characters like line breaks within cell values.

Even though standard CSV formatting escapes line breaks inside quotation marks, in the version of Ruby used by Canvas, CSV::foreach does not account for this properly, causing Canvas to misinterpret the line break as the start of a new row. This misinterpretation disrupts the structure of the data, causing Canvas to throw a generic error because it cannot match the parsed content to the expected format of the gradebook.

Still need help? Reach out to Canvas support or the Technology & Learning Program for further assistance.

Print Article