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 error messages, what triggers each, an example, and how to resolve them.
| Index | Error Message | Error Trigger | Example | Solution |
|---|---|---|---|---|
| 1 | The character count exceeds the database column width | Text size beyond the limitation of the data field | 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 | File does not exist | Forget packing files listed in your template | 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 | Not an integer (also: "A positive integer is expected", "A non-negative integer is expected", "Not a real number", or "… outside the range for an Oracle number") | Text in an expected numeric field, or a number of the wrong kind (negative where positive is required, decimal where an integer is required, or a value too large) | The Numeric Type check "positive" in field "Target Enrollment" "100 patients" | Pay attention to the “data type” note in the data field Comments (mouse over the data field name in the Excel template). Enter a bare number with no units, no thousands separators, and no text; use the exact numeric kind the field expects (integer vs. real, positive vs. non-negative). |
| 4 | User defined ID is already in database | User_defined_ID has been used in the workspace | 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 already in package | User_defined_ID is not unique in your template | 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 already in package | User_defined_ID is not unique in your template | 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 | Missing conditional required value | Conditional Required Data Field is empty | 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 | Data row is missing results | Required Data Field is empty | 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 | Missing required value | Required Data Field is empty | 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 | Missing required value | Required Data Field is empty | 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 compound template is missing | Required Data Field is empty | 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 compound template is missing | Required Data Field is empty | 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 compound template is missing | Required Data Field is empty | 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 | 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}. | Template is an older version than the Validator expects | 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 | 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}. | Template is a newer version than the Validator expects | 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 reported in template does not match preferred vocabulary. See template documentation for preferred vocabulary terms. | Value not in the Controlled Vocabulary list for that field | 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 | The value reported does not match a preferred value to map. See template documentation for preferred vocabulary terms. | Value not recognized by a Mapped or Preferred Vocabulary field | 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. Note: this still appears as an entry in the validation report; it flags that no preferred term could be mapped, not that your data is rejected. |
| 18 | ForeignKeysLogic.error.unknown.user.defined.id.foreign.key / ForeignKeysLogic.error.unknown.accession.id.foreign.key | Reference to another record cannot be resolved (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 | The Excel file name has same prefix as a template file name | Legacy binary .xls spreadsheet (Excel 97–2003) whose name matches a template | Your package contains basic_study_design.xls (old binary format) where a template file is expected. | Both tab-delimited .txt and modern .xlsx are accepted template formats and are validated/parsed directly; the legacy .xls binary format is not. Re-save the file as .xlsx (in Excel, File → Save As → "Excel Workbook") or as tab-delimited .txt (File → Save As → "Text (Tab delimited)"), and include that file instead. |
| 20 | The date format is either DD-MMM-YY or DD-MMM-YYYY where day (DD) is one or two digits 01..31 appropriate to the month, month (MMM) is a case-insensitive value (Jan, Feb, …, Dec), and year is either two digits (YY, e.g. 05 = 2005) or four digits (YYYY). | A date field entered in the wrong format | In basic_study_design, "Actual Start Date" contains 2005-02-06 or 02/06/2005 instead of 06-Feb-2005. | Use DD-MMM-YYYY (e.g. 06-Feb-2005); two- and four-digit years are both accepted, but numeric months, slashes, and ISO (YYYY-MM-DD) formatting are not. Excel may silently reformat date cells — set the column format to Text before typing, and confirm the cell shows exactly DD-MMM-YYYY. |
| 21 | Value and unit must both be empty or non-empty | A result value entered without its unit, or a unit without a value | In a results template, "Result Value Reported" is 10 but "Result Unit Reported" is blank (or vice versa). | These paired fields must be filled together. Provide both the value and its unit, or leave both empty. |
| 22 | The template does not contain the row whose first cell is the (case-insensitive) template name … and the row also contains the cell "Schema Version {1}" — or — Cannot find header row in template file — or — Unable to find start of vertical compound template, possible explanations include a missing section header or a typo in a section header |
The template's control row, its "Column Name" header row, or a compound section header was edited, deleted, reordered, or misspelled | The top "… Schema Version 3.37" row was removed from protocols.txt; or the "Column Name" row was renamed; or a section header in basic_study_design was typed as "study personnel" instead of "Study_Personnel". | Do not delete, rename, reorder, or retype the fixed rows the template ships with (the template-name / Schema Version row, the "Please do not delete or edit this column" row, the "Column Name" header row, and each compound section header). If in doubt, start from a fresh copy of the template and paste only your data rows into it. |
| 23 | Missing required column in column header | A required column was removed from the header row (as opposed to left blank in a data row) | The "Age Unit" column was deleted from the subjectHumans header row. | Keep every column the template ships with in the header row, even columns you leave empty; re-add the missing one from a fresh template copy. This differs from a missing value (rows 8–10) — here the whole column is gone. |
| 24 | Duplicate file based on case-insensitive spelling — or — Duplicate template file based on case-insensitive spelling |
Two files in the package whose names differ only by letter case, or the same template supplied in more than one format | The package contains both protocols.txt and protocols.xlsx; or both Reagents.txt and reagents.txt. | Include each template once, in a single format (.txt, .xlsx, or .json), and remove the extra copy. Make sure no two files anywhere in the package share a name that differs only by case. |
| 25 | The workspace data file schema version ({0}) is older than the code schema version ({1}). You need to download a current workspace data file. (also the "… is newer …" variant) | The workspace data file used by the Validator is out of date relative to the Validator code — not a problem with your template | You run the Validator against a workspace data file downloaded months ago (schema 3.35) while the Validator is on 3.37. | This is about the workspace data file, not your template (contrast rows 14–15). Download a fresh workspace data file from ImmPort and re-run. If it reports "newer", the Validator application itself is behind — contact ImmPort_Helpdesk@immport.org. |
| 26 | Unable to unzip package — or — IO Exception made template file unreadable / An Exception made template file unreadable |
The uploaded archive is not a readable .zip, or a file inside it cannot be read | A password-protected or partially-uploaded zip; a .rar or .7z renamed to .zip; a template saved in a binary format but named ".txt". | Repackage as a plain, unencrypted .zip (no password, no split/multi-part archive). Re-download and re-save any template that will not open, and confirm each template file is genuine tab-delimited text, .xlsx, or .json — not a renamed binary. |