Data Package Validator

The Validator is an online tool that checks the format and content of the files in the data package and reports issues. If there are any errors in the validation report, fix the first errors that are indicated and rerun the validation process. The errors encountered first may have effects on later files that are validated. It is highly recommended to use the Validator before sending data into ImmPort as part of the data upload process.

Troubleshooting Common Validation Errors

The table below lists common Validator errors, what triggers them, an example, and how to resolve them.

Index	Error Trigger	Error Message	Example	Solution
1	Text size beyond the limitation of the data field	The character count exceeds the database column width	In assessments template, the assessment_panel_status has Expected Length "40", but the input text has Length "45"	Pay attention to the limitation “varchar(size limitation )” in the data field Comments by mouse over the data field name in the Excel template.
2	Forget packing files listed in your template	File does not exist	Missing the file MidMicrobiomeData.xlsx which is specified in your experimentSamples template, but missed in your upload package.	Make sure all files specified are packed in your upload package. Check file counts in your directory before uploading.
3	Text in an expected integer field	Not an integer	The Numeric Type check "positive" in field "Target Enrollment" "100 patients"	Pay attention to the “data type integer” in the data field Comments by mouse over the data field name in the Excel template.
4	User_defined_ID has been used in the workspace	User defined ID is already in database	User Defined ID with value "100" in the Table study	This is the case of your ID has been used in the same workspace. Tip: try to use a long unique ID specific to your study, such as PMID, preprint ID, etc.
5	User_defined_ID is not unique in your template	User defined ID is already in package	In subjectHumans template, one subjectID has been used in >1 rows	Check the subjectID in your template and correct the error (e.g. remove duplicated row).
6	User_defined_ID is not unique in your template	User defined ID is already in package	In assessments template, one subjectID has been used in >1 rows. The same error message can also appear in the assessment_component template.	In the assessments template: if you have multiple assessment panels for a subject, prepare one template per panel to avoid the issue of multiple rows for a subject. However, it is OK to have multiple assessment components for a subject — just expand the 15 component fields (from User Defined ID to Who Is Assessed) row-wise, one after another, so multiple components are in the same subject row. Note for the assessment_component template: this is a different situation. A subject repeating across multiple rows is expected and valid there — each row is a separate component. Do not try to consolidate the rows. This error means a row's own User Defined ID value is not unique, not the Subject ID. Check that every row in the template has a distinct User Defined ID.
7	Conditional Required Data Field is empty	Missing conditional required value	Required Column for Field "Race Specify" If Race="Other"	If you select "Other" in the Race dropdown list, you need to specify the race with free text in the "Race Specify" field — you cannot leave it blank. Conditionally required fields are not highlighted in bold font in the template, so they are easily overlooked.
8	Required Data Field is empty	Data row is missing results	In subjectHumans template, missing value in the required "Exposure Process Reported" field	If the value is not relevant to you, choose "unknown" in the dropdown list.
9	Required Data Field is empty	Missing required value	The Rule check "Required Column" for Field "Title In Study". The row has ID field(s) "User Defined ID" and value "investigator_1"	In the study_personnel section of the basic_study_design template, the field "Title In Study" is a required field.
10	Required Data Field is empty	Missing required value	The Rule check "Required Column" for Field "Site Name". The row has ID field(s) "User Defined ID" and value "author_1"	In the study_personnel section of the basic_study_design template, the field "Site Name" is a required field.
11	Required Data Field is empty	Required compound template is missing	The Compound Template has value "planned_visit"	The "planned_visit" section in the basic_study_design template cannot be empty. If your study doesn't have a planned visit, put at least 1 row there, e.g. 24633240_PV1 (for User Defined ID), Sample collection (for Name), 1 (for Order Number), 0 (for Min Start Day). You are not allowed to reuse the planned_visit accession from a previous study.
12	Required Data Field is empty	Required compound template is missing	The Compound Template has value "inclusion_exclusion"	The "inclusion_exclusion" section in the basic_study_design template cannot be empty. Put at least one criterion there. You are not allowed to reuse the "inclusion_exclusion" accession from a previous study.
13	Required Data Field is empty	Required compound template is missing	The Compound Template has value "study_2_protocol"	The "study_2_protocol" section in the basic_study_design template cannot be empty. Put at least one protocol there. It is OK to reuse the protocolID accession (e.g. PTL10759) from a previous study.
14	Template is an older version than the Validator expects	The template with schema version ({0}) is older than the code schema version ({1}). You are using an older version of the template than the code will accept, please use the template with schema version {1}.	You upload subjectHumans.txt saved from a template downloaded some time ago, tagged Schema Version 3.35, but the current template version is 3.37.	Download the current version of the template from the Submission Templates page and re-enter your data, or copy your data into the new template. Do not edit the Schema Version row by hand.
15	Template is a newer version than the Validator expects	The template with schema version ({0}) is newer than the code schema version ({1}). You are using a newer version of the template than the code will accept, please use the template with schema version {1}.	You upload a template tagged Schema Version 3.38, but the deployed Validator/upload-server code still expects 3.37.	This means the Validator or upload-server has not yet been updated to match a template change that was already released. Contact ImmPort_Helpdesk@immport.org rather than trying to work around it — do not hand-edit the Schema Version row.
16	Value not in the Controlled Vocabulary list for that field	Value reported in template does not match preferred vocabulary. See template documentation for preferred vocabulary terms.	In basic_study_design template, the "Age Unit" column contains "yrs", but the allowed values (from lookup table lk_time_unit) are Days, Hours, Minutes, Months, Seconds, Weeks, Years.	Controlled Vocabulary fields only accept an exact value from the dropdown list in the Excel template — free text is rejected outright (unlike Mapped/Preferred Vocabulary fields, below). Open the Excel version of the template and select the value from the dropdown rather than typing it.
17	Value not recognized by a Mapped or Preferred Vocabulary field	The value reported does not match a preferred value to map. See template documentation for preferred vocabulary terms.	In arm_or_cohort template, "Type Reported" contains a free-text value that isn't found in the lk_arm_type_pref_mapping table, so no "Type Preferred" value can be automatically assigned.	Unlike Controlled Vocabulary fields, your reported value is still accepted and saved — but the automatic "preferred" mapping (e.g. Type Preferred) is left blank. If you want the preferred term populated, check the template documentation for the closest matching preferred term and use it instead.
18	Reference to another record cannot be resolved (foreign key)	ForeignKeysLogic.error.unknown.user.defined.id.foreign.key / ForeignKeysLogic.error.unknown.accession.id.foreign.key	In study_2_protocol template, "Protocol ID" references a protocol user-defined ID or accession that isn't defined anywhere in this package or already in the workspace.	Make sure every ID/accession you reference (Protocol ID, Arm or Cohort ID, Planned Visit ID, Biological Sample ID, etc.) is either defined in the same upload package or already exists in the target workspace, and that it's spelled exactly the same way in both places.
19	Excel file left in the package instead of the tab-delimited text file	The Excel file name has same prefix as a template file name	Your package contains basic_study_design.xlsx but not basic_study_design.txt (or contains both, with conflicting content).	The Excel (.xlsx) template is provided for convenience — comments and dropdown lists — but the file actually uploaded and parsed must be saved as tab-delimited text (.txt) with the same base name. In Excel, use File → Save As → "Text (Tab delimited)" and include only the resulting .txt file in your package.