Common Form Definition Upload Errors

Modified on Fri, 20 Nov at 4:56 PM

 

ℹ️ This page is for Data Managers responsible for study design.

 

In OpenClinica, a Form Definition is a filled-in Form Template spreadsheet. When a Form Definition upload fails, Study Designer shows a message for each problem it found in the spreadsheet. Each message names the item, group, or column that caused the problem. This article lists the most common Form Definition upload errors, what each one means, and how to fix it.

 

For what each column of the template does, see Build a Form with the Form Template.


 

How do I fix a Form Definition upload error?

 

In OpenClinica, fix every message in the list, then upload the spreadsheet again.

  1. Read each message. In this article, "X" stands for the Item Name, group name, or value that the message shows.
  2. Find the row or column that the message names in the spreadsheet, and use the tables in this article to fix it.
  3. Save the spreadsheet, and on the form in Study Designer, click Upload again.

 

ℹ️ Note: Form Designer shows similar messages, with Item and field in place of Element and column. For example, Element "X" cannot have Choices with the same name appears in Form Designer as Item "X" cannot have Responses with the same text.

 

File and Settings Errors

 

These OpenClinica upload errors are about the file you upload or the settings sheet. Use this table to find the fix.

MessageWhat to do
You must upload your form in XLS or XLSX format. Something has gone wrong. Your form is not in the expected format.The upload did not include a spreadsheet, for example because only a CSV or media file was selected. Select the spreadsheet and all of its CSV and media files, and upload them together.
You cannot include more than one XLS or XLSX file per upload. Please upload your forms individually.Upload each form separately. You can only upload media files and CSV files with the spreadsheet.
Something has gone wrong. You cannot have an XLS or XLSX file as a media or external list file for your form. Please upload your forms only with media and CSV files.Upload only one spreadsheet. Save external choice lists as CSV files.
The "version" column in the "settings" worksheet must have a value in row 2.Enter a version, such as 1, in row 2 of the settings sheet.
A form version cannot be replaced after it has been published to Production. You must upload it as a new form version.Change the version on the settings sheet and upload again. In Study Designer, versions published to Production have a lock icon next to them. Use a version that does not have a lock icon next to it, or one that is not already in the list.
Your form contains invalid language labels. Languages must be labelled with the name and code, E.g. "English (en)"Add a code in parentheses to every language column header and to default_language, for example label::Spanish (es). See Language Support.
Form definition must include at least one item that is not type "calculate".Add at least one question or note to the survey sheet.

 

Name Errors

 

These OpenClinica upload errors are about Item Names and group names in the survey sheet's name column. Use this table to find the fix.

MessageWhat to do
Elements and/or Groups cannot have the same name: "X"Give every item and group on the form a unique name.
Element "X" must not have a value in column "name" longer than 40 characters.Shorten the Item Name to 40 characters or fewer.
Names must begin with a letter or underscore.Change the name so that it starts with a letter or an underscore. Use only letters, numbers, and underscores.

 

Item Group Errors

 

These OpenClinica upload errors are about the bind::oc:itemgroup column, which sets the Item Group (the dataset or domain an item is stored in). Use this table to find the fix.

MessageWhat to do
Element "X" must be assigned to an Item GroupEnter a value, such as VS, in the bind::oc:itemgroup column for that item. Leave it blank only on group rows and notes.
Element "X" must have a value in column 'bind::oc:itemgroup' that contains only letters, digits, or underscores and must not start with digits.Change the Item Group so that it uses only letters, numbers, and underscores, and does not start with a number.
Element "X" must have the same value in column 'bind::oc:itemgroup' as all other elements in Repeating Group "R"Use the same Item Group for every item in the repeating group.
Repeating Group "R" cannot be nested within Repeating Group "S"Move the inner repeating group out of the outer one. Repeating groups cannot be nested.
Read-only note element "X" cannot have a value in column 'bind::oc:itemgroup'Clear the bind::oc:itemgroup value for that note. Notes do not store data, so they cannot have an Item Group.
Read-only note element "X" cannot have a value in column 'bind::oc:description'Clear the bind::oc:description value for that note. Notes do not store data, so they cannot have an item description.
Read-only note element "X" cannot have a value in column 'bind::oc:briefdescription'Clear the bind::oc:briefdescription value for that note. Notes do not store data, so they cannot have a brief description.

 

Choice List Errors

 

These OpenClinica upload errors are about the response options on the choices sheet. Use this table to find the fix.

MessageWhat to do
Element "X" cannot have Choices with the same name: "v"Make each option's name unique within its list.
Choice "v" for element "X" must have a label.Add a label for the option.
Element "X" must not have total choice labels longer than 4,000 charactersShorten the labels, or move the list to a CSV file. The limit counts the labels in all versions of the form.
Element "X" must not have total choice names longer than 4,000 charactersShorten the names, or move the list to a CSV file. The limit counts the names in all versions of the form.
Unknown question type 'select_one'.Add the list name after select_one in the type column, for example select_one yn. The list name must match a list_name on the choices sheet.
[row n] List name not in choices sheet: 'X'The list name in the type column of row n does not match any list_name on the choices sheet. Correct the spelling, or add the list to the choices sheet.

 

Item Type and Calculation Errors

 

These OpenClinica upload errors are about the type, calculation, and readonly columns. Use this table to find the fix.

MessageWhat to do
Element "X" has an unsupported data typeUse a supported item type. The time, dateTime, geopoint, geotrace, geoshape, and barcode types are not supported. See Item Types and Appearance Reference.
Element "X" cannot have a value in column "calculation" unless it is read-only.Set readonly to yes, add a trigger, or change the type to calculate.
Element "X" cannot be defined as type = calculate and required. This element will never be visible on the form.Remove the value in the required column of the calculate row. Calculate items are never shown, so they cannot be required, read only, or have an edit check. Similar messages appear for readonly and constraint.

 

Errors When You Change a Form in a New Version

 

In OpenClinica, some changes are not allowed once a form version exists, because they would split data collected under earlier versions. When you overwrite a version that has been published to Test, the same messages end with "because this form version has already been published to Test" instead. Use this table to find the fix, and see Versions and Changing Forms After Go-Live for the full rules.

MessageWhat to do
Element "X" cannot have a different data type between versions of the formKeep the item's original type. To collect a different type of data, add a new item with a new Item Name.
Element "X" cannot have a different value for column 'bind::oc:itemgroup' between versions of the formKeep the item's original Item Group. To store the data in a different Item Group, add a new item with a new Item Name.
Repeating Group cannot be changed to a non-Repeating Group in other versions of the form: "R"Keep the group repeating, as in earlier versions. To collect the data without repeats, add a new non-repeating group with new items.
Non-Repeating Group cannot be changed to a Repeating Group in other versions of the form: "R"Keep the group non-repeating, as in earlier versions. To collect repeating data, add a new repeating group with new items.
Elements in a Repeating Group cannot be moved out of that Repeating Group in other versions of the form: "X"Keep the item in its repeating group. To collect it outside the repeating group, add a new item with a new Item Name.
Elements not in a Repeating Group cannot be moved into a Repeating Group in other versions of the form: "X"Keep the item outside the repeating group. To collect it in a repeating group, add a new item with a new Item Name.

 

eConsent and Contact Data Errors

 

These OpenClinica upload errors are about eConsent signature items and encrypted contact data (PII) items. Use this table to find the fix.

MessageWhat to do
Consent signature items cannot be included in repeating groupsMove the eConsent signature item out of the repeating group.
Signature items can only be used in non-repeating Visit Events.Use the form only in non-repeating visit events.
Item "X" is the contact data field Full Date of Birth and must be of type dateChange the item's type to date.

 

Frequently Asked Questions

 

Why does my OpenClinica Form Definition upload fail?

 

An OpenClinica Form Definition upload fails when the spreadsheet breaks a rule, such as an item with no Item Group, two items with the same name, or a change that is not allowed in a new form version. Study Designer lists every problem it finds. Fix each one in the spreadsheet, then upload it again.

 

What does Element "X" mean in an OpenClinica upload error?

 

In an OpenClinica Form Definition upload error, Element is an item on the survey sheet, and the value in quotation marks is its Item Name from the name column. Search the survey sheet for that name to find the row to fix. Form Designer shows the same kind of message with the word Item instead.

 

Can I change an item's Item Group or type in a new OpenClinica form version?

 

No. Once a form version exists in OpenClinica, an item keeps its Item Group and data type in every later version, and an upload that changes either one fails. To store the data differently, add a new item with a new Item Name. See Versions and Changing Forms After Go-Live.


 

Related Articles

 

These OpenClinica articles cover building a Form Definition and uploading it.


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article