When creating CSV Templates, you will undoubtedly encounter errors that need to be fixed. These can be caused by problems or edge cases in the file, or by errors and typos in your template. Sometimes these error messages need a little more explanation, especially if it’s the first time you’ve seen them. This help guide sets out some of the most common errors, what they mean and how to fix them.
- User Types
- Only Global Admins can create CSV import templates and upload CSV files.
- Pricing
- Available on paid plans (Analyst, CLO, and Enterprise).
- Expertise
- Only Experts should debug CSV import templates.
Please note: This guide is relatively high level given the range of possible errors when processing CSV files. Contact Watershed support if you need more specific help.
Failed to Parse Handlebars template
Example Error Message
inline doesn't match inlin - 27:4
What It Means
This error message, appearing underneath the template and as a red X within the template, indicates that the Handlebars opening and closing tags do not match. In the particular example above, the opening tag {{#*inline 'object'}} does not match the closing tag {{/inlin}}. Notice that the closing tag says inlin instead of inline.
How to fix it
To fix this error, make sure your opening and closing tags match exactly.
Failed to Parse file
Example Error Message
Failed to parse file at row [516731]: Json mapping exception: unexpected character ('x' (code 120)): Expected separator ('"' (code 34)) or end-of-line
at [Source: java.io.BufferedReader@437c6e26; line: 516747, column: 423]
at [Source: java.io.BufferedReader@437c6e26; line: 516747, column: 398] (through
reference chain: Object[][15])
What It Means
An error message that begins “Failed to parse file” indicates that the uploaded CSV file is invalid in some way. Watershed supports UTF-8 comma separated files, which can use quotes to enclose text. Any quotes used in fields must be escaped with an additional double quote. Full details of the requirements of CSV files supported by Watershed are outlined in RFC 4180.
In the particular example above, the code that parses the CSV file has found an ‘x’ character when it expected to next find either a separator or a new line. This might indicate an unescaped quote where the next character after the quote is ‘x’.
How to fix it
To fix this error, the uploaded CSV file must be fixed so as to be a valid UTF-8 CSV file. You should check that:
- The file is UTF-8 encoded.
- Fields are separated by commas.
- Any quotes appearing in the data are properly escaped with an additional quote character.
- Any strings have been encapsulated in quotes, especially if they include commas, line breaks or quote characters.
The line numbers referenced in the error message can be helpful in tracking down specific issues. The first number in the error message (“516731” in the example above) is the affected row of the CSV data. The other line number given (“516747” in the example above) is the affected line of the file. These two numbers can be different if the file contains rows of data that span more than one line of the file, for example if a cell includes a string of text that includes line breaks. Use the row number if looking at the data using spreadsheet software; use the line number if looking at the data in a text editor.
Failed to process template
Example Error Message
Failed to process template for row [2]: Json parse exception: unexpected close marker ']': expected '}' (for OBJECT starting at [Source: { "statements": [ { "id":"fd41c918-b88b-4b20-a0a5-a4c32391aaa0", "timestamp": "2015-11-18T12:17:00+00:00", "actor":{ "objectType": "Agent", "name":"Project Tin Can API", "mbox":"mailto:user@example.com" , "verb":{ "id":"http://example.com/xapi/verbs#sent-a-statement", "display":{ "en-US":"sent" } }, "object":{ "id":"http://example.com/xapi/activity/simplestatement", "definition":{ "name":{ "en-US":"simple statement" } } } } ] }; line: 3, column: 5]) at [Source: { "statements": [ { "id":"fd41c918-b88b-4b20-a0a5-a4c32391aaa0", "timestamp": "2015-11-18T12:17:00+00:00", "actor":{ "objectType": "Agent", "name":"Project Tin Can API", "mbox":"mailto:user@example.com" , "verb":{ "id":"http://example.com/xapi/verbs#sent-a-statement", "display":{ "en-US":"sent" } }, "object":{ "id":"http://example.com/xapi/activity/simplestatement", "definition":{ "name":{ "en-US":"simple statement" } } } } ] }; line: 26, column: 4]
What It Means
An error message that begins “Failed to process template” indicates that there has been an error running the template on a particular row of the file. This is normally because the template has resulted in invalid JSON. Invalid JSON is normally caused by missing or additional JSON syntax characters such as " , { } [ or ].
How to fix it
The easiest way to identify the cause of this error is to copy and paste the generated JSON from the error message into a tool which can validate the JSON and highlight the issue. (One free tool that can be used for this is JSONTLint.com).
For example, the JSON in the error above can be reformatted as shown below. Note that the closing } on the actor object is missing.
{
"statements": [{
"id": "fd41c918-b88b-4b20-a0a5-a4c32391aaa0",
"timestamp": "2015-11-18T12:17:00+00:00",
"actor": {
"objectType": "Agent",
"name": "Project Tin Can API",
"mbox": "mailto:user@example.com",
"verb": {
"id": "http://example.com/xapi/verbs#sent-a-statement",
"display": {
"en-US": "sent"
}
},
"object": {
"id": "http://example.com/xapi/activity/simplestatement",
"definition": {
"name": {
"en-US": "simple statement"
}
}
}
}]
}
If the error only occurs on some lines and not others, it may be that certain conditions of your logic functions are leading to errors. Additional or missing commas can occur if you are not careful with how logic functions are structured.
Template error
Example Error Message
Template error at line 5, column 17: Error parsing value in (toDateTime '41-Fenuarble-19' '41-Fenuarble-19'). Parse exception unparseable date: "41-Fenuarble-19"
What It Means
An error message that begins “Template error” indicates that there has been an error processing the template, normally because of a syntax error with one of the functions used or the data passed to it. In the example above, the toDateTime function has been passed the string “41-Fenuarble-19”, which is an invalid date since there is no month called “Fernuarble”.
How to fix it
Most commonly toDateTime function errors can occur with a previously working template if the format of the date in the uploaded CSV file changes. This can happen if either the original file that the template was based on, or the latest file that’s throwing errors, has been edited in Excel. See How can I safely open a CSV file in Excel? for how to avoid this.
Other template errors can be fixed by addressing any relevant syntax errors. Sometimes additional translation of data needs to be added to the template in order to cope with bad or unexpected values in the fields being processed. For example, a replace function might be used to re-format a string in certain circumstances, or logic functions might be used to skip rows containing bad data entirely.
Failed to parse into statements
Example Error Message
Failed to parse row [2] into statements: Invalid argument exception: statement at index 0 is not valid according to the schema: instance failed to match all required schemas (matched only 0 out of 1)
What It Means
An error message that begins “Failed to parse row [n] into statements” indicates that the xAPI statement or statements generated by the row of the template are not valid xAPI. Some of the time this will be followed by a clear and helpful error that explains which part of the statement is invalid and how.
The error above indicates a problem with the statement other than one of the more common errors that we provide a specific error for. There is some other error with the statement.
How to fix it
A good approach to finding the specific issue is to remove parts of the template that generate the xAPI statement in order to find the part of the statement causing the problem. Of course, you will need to keep the parts of the template generating the required properties:
- actor.mbox or actor.account
- verb.id
- object.id
(If you get down to just these required properties, you know there is a problem with one of them).
Keep a copy of your full template saved before you delete anything so you can re-add your full template piece by piece once you have corrected errors.
Conflicting Persona
Example Error Message
Incoming person Thor Odinson (customId: Thunder God) conflicts with Bruce Banner (customId: Hulk) on persona:
- strongest@avengers.org
The persona has been assigned to Thor Odinson (customId: Thunder God) only.
What It Means
CSV imports can be used to assign multiple personas to a person. This error means that a single import has attempted to assign the same persona to multiple people, but Watershed only allows a persona to be assigned to one person.
The most common cause of this error is the upload is trying to associate an email address to multiple Watershed people records. It can also happen when a single person has multiple accounts with multiple (unique) primary identifiers (so appears to be multiple people and therefore has multiple Watershed person records), which share other secondary identifiers.
Related:
How to fix it
Watershed’s default behavior is to assign the persona to just one of the people (the last one to appear in the most recent file uploaded). This may be satisfactory in which case no action is required. If you require the persona to be associated with a specific person record, the field which you are generating the actor from in the source CSV file needs to be updated to use the primary identifier of the user required. Alternatively, you could add some logic to the import template so that only that person is assigned that persona, but it is always preferable to fix the source data.
Conflicting Statement IDs
Example Error Message
Conflicting statements with ID 'ae5642c4-0e00-4992-8544-41e3cf62a3db' detected
What It Means
xAPI statements all have a unique id and no two statements can have the same id. This can be useful in order to avoid duplicate data when importing CSV data that may have been imported before.
In these cases, templates can use the uuid function. This generates a Universally Unique Identifier (UUID) based on a combination of any number of parameters. The function is such that every time exactly the same values are passed, the same UUID is generated. This can be useful for ensuring the same statement id is used for all statements recording a particular interaction, to avoid tracking the same interaction twice. When Watershed receives a statement with the same id as an existing statement, the new statement is not stored.
How to fix it
Watershed will log an error message as a warning whenever a CSV import attempts to save a statement with an id that already exists. Often these messages simply indicate the uuid function working as intended and can be ignored. However if you are missing data you expected to be imported and see these errors on rows that should have generated that data, that can indicate a problem with how the uuid function has been used in the template. Check that the parameters used in the uuid function really do combine to indicate a unique record of the interaction being recorded.