Troubleshooting Errors
Paste part of the error message into the search box to find its cause and fix. Each error has a stable ID (for example E-07) that you can quote to the helpdesk or link to directly.
Fix the first errors first
Validation reports errors in the order it finds them, and one early problem can cause many later errors. Fix the first few, then validate again.
| ID | Message | Cause | Example | How to fix |
|---|---|---|---|---|
| E-01 | The character count exceeds the database column width Values & formats |
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" | Shorten the text. Each field's maximum length is on its field page (Text, max N characters) and in the comment on the column header in the Excel template. |
| E-02 | File does not exist Package & files |
A file named in a template is missing from the package | 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. |
| E-03 | 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") Values & formats |
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). |
| E-04 | User defined ID is already in database IDs & references |
User_defined_ID has been used in the workspace | User Defined ID with value "100" in the Table study | The ID is already used in this workspace, perhaps by an earlier upload or another study. Choose a new ID. Tip: include something unique to the study, such as a PMID or preprint ID, in your IDs. |
| E-05 | User defined ID is already in package IDs & references |
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). |
| E-06 | User defined ID is already in package IDs & references |
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. |
| E-07 | Missing conditional required value Required fields |
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. |
| E-08 | Data row is missing results Required fields |
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. |
| E-09 | Missing required value Required fields |
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. |
| E-10 | Missing required value Required fields |
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. |
| E-11 | Required compound template is missing Required fields |
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. |
| E-12 | Required compound template is missing Required fields |
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. |
| E-13 | Required compound template is missing Required fields |
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. |
| E-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}. Versions |
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 Template Catalog and re-enter your data, or copy your data into the new template. Do not edit the Schema Version row by hand. |
| E-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}. Versions |
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. |
| E-16 | Value reported in template does not match preferred vocabulary. See template documentation for preferred vocabulary terms. Vocabulary |
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. |
| E-17 | The value reported does not match a preferred value to map. See template documentation for preferred vocabulary terms. Vocabulary |
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. |
| E-18 | ForeignKeysLogic.error.unknown.user.defined.id.foreign.key / ForeignKeysLogic.error.unknown.accession.id.foreign.key IDs & references |
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. |
| E-19 | The Excel file name has same prefix as a template file name Package & files |
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. |
| E-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). Values & formats |
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. |
| E-21 | Value and unit must both be empty or non-empty Values & formats |
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. |
| E-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 Template structure |
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. |
| E-23 | Missing required column in column header Template structure |
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 (E-08 to E-10) — here the whole column is gone. |
| E-24 | Duplicate file based on case-insensitive spelling — or — Duplicate template file based on case-insensitive spelling Package & files |
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. |
| E-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) Versions |
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 (compare E-14 and E-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. |
| E-26 | Unable to unzip package — or — IO Exception made template file unreadable / An Exception made template file unreadable Package & files |
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. |
| E-27 | {0} for {2} is already defined for a {1} in {2} IDs & references |
The same subject and study pair appears twice in the arm_2_subject section of one package |
study_design_edit links Subject_001 to two arms of the same study in one file | Keep one row per subject per study. Linking a subject to arms in different studies is fine (see Sharing subjects across studies). |
| E-28 | Two or more arms assigned to the subject are in the same study IDs & references |
A subject is assigned to more than one arm of the same study | Subject_001 is assigned to both ARM_A and ARM_B of study SDY100 | A subject can belong to only one arm in a study. Remove the extra assignment. |
| E-29 | The study accession associated with an entity is not equal to upload's study accession Package & files |
The package contains data for more than one study | One zip contains subjects for two different studies | Make one package per study (R-01). |
| E-30 | Row has incomplete data Required fields |
None of a group of columns is filled in, but at least one of them is required | A treatments row with Amount, Duration and Temperature all empty | Fill in at least one column of the group. The field page notes which columns form the group. |
| E-31 | ImmPort result template is not present — or — No result file provided — or — ImmPort result template was indicated in template but a custom result file is provided — or — Upload package providing a non-ImmPort result file, but an ImmPort result file provided Template structure |
The ImmPort Template? column in an experiment samples template doesn't match the results you included | experimentSamples.HLA says ImmPort Template? = Yes, but HLA_Typing.txt is missing from the package, or a Result File Name is also filled in | Yes: include the ImmPort results template and leave Result File Name empty. No: put your file's name in Result File Name and include that file. Never both. |
| E-32 | Population maker "{0}" is not known, needs to be added to list of analytes (lk_analyte) or non-analyte markers (lk_cell_populaton_marker) Vocabulary |
A cell population definition in flow cytometry or CyTOF data uses a marker ImmPort doesn't know | A gating definition uses a misspelled marker name | Check the spelling against lk_analyte. If the marker is genuinely new, ask the helpdesk to add it. |
| E-33 | Duplicate data row Template structure |
Two data rows in a template are identical | The same subject row is pasted twice in subjectHumans | Remove the duplicate row. |
Still stuck?
- Check the field's page in the template documentation. It shows conditional-required triggers, allowed values and maximum lengths.
- See Validation Rules for what each rule type checks. This helps when a message names a rule such as
check-value-in-entity. - Email the ImmPort Helpdesk with the exact error text, the template name and the row number. Conditional rules are specific to each template, so a fix for a similar-looking error elsewhere may not apply.