> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmosid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Common Metadata Upload Errors

**If you encounter errors during metadata upload, please check for the following issues:**

* **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. |

If you have followed all of the above and continue to have issues, please contact support with your metadata file attached for further assistance.