- Duplicate Column Names: All column headers must be unique. For example, do not include the same field (such as “Visit Date”) more than once. Duplicate headers will block uploads.
- Datetime Format Requirements: Date fields must use ISO 8601 format (
YYYY-MM-DD), unless otherwise specified. Spreadsheet editors (like Excel) often auto-format dates; double-check and reformat as needed. For best results, use Numbers or CSV tools that preserve formatting. - Character Limits: Text field values must not exceed 32 characters.
- No Special Characters or Spaces in Field Labels: For custom fields, avoid all special characters and spaces in labels.
- File Encoding: Save your metadata as UTF-8 encoded CSV to prevent issues with hidden or non-printable characters.
Error messages reference
Below are the specific error messages you may encounter and how to resolve them:Label and uniqueness errors
| Error | Resolution |
|---|---|
| Duplicate label detected: “label” conflicts with an existing metadata label. | Rename the label so all metadata labels are unique. |
| Missing metadata label: Each metadata field must have a label name. | Add a Metadata label and try again. |
| Invalid label: “label” cannot be empty or contain only spaces. | Enter a meaningful metadata label. |
System metadata errors
| Error | Resolution |
|---|---|
| System metadata is read-only: “label” cannot be edited. | Revert it to its original value. System metadata fields are protected and cannot be modified. |
Metadata type errors
| Error | Resolution |
|---|---|
| Metadata type mismatch: “label” expects type X, but the uploaded value is Y. | Update the values or change the metadata label type to match. |
| Missing metadata type: Each metadata field must specify a type (e.g., text, decimal, datetime). | Define the type and try again. |
Template integrity errors
| Error | Resolution |
|---|---|
| Template error detected: The metadata template appears to be corrupted or modified incorrectly. | Download a fresh template and re-enter your metadata. |
| Invalid template format: This file does not match the required Cosmos-Hub metadata template. | Download the latest template and upload it without modifying its structure. |
Numeric value errors
| Error | Resolution |
|---|---|
| Invalid Values: “label” must contain a numeric value. | Remove non-numeric characters and try again. |
| Invalid number format: “label” expects a numeric value, but received “input”. | Enter a valid number (e.g., 3, 3.14). |
Date value errors
| Error | Resolution |
|---|---|
| Invalid date: “label” must be a valid date. | Use one of the supported date formats. |
| Invalid date format: “label” must be a valid date using a supported format. | Use ISO 8601 format (YYYY-MM-DD) or another supported format. |
Sample matching errors
| Error | Resolution |
|---|---|
| No matching samples found: The sample IDs in your metadata file do not match any of the selected samples. | Verify that sample names are spelled correctly and match existing sample IDs exactly. |