10 Common XLSForm Mistakes and How to Fix ThemXLSForm is a widely used standard for authoring forms in Excel (or similar spreadsheet tools) and converting them into XML-based forms for platforms like ODK, KoBoToolbox, and SurveyCTO. While it simplifies form building, users—especially beginners—often run into recurring mistakes that cause errors, invalid data, or unexpected behavior on devices. This article walks through ten of the most common XLSForm mistakes, explains why they happen, and provides clear fixes and best practices.
1 — Incorrect column names or typos in the survey sheet
One of the most frequent errors is misspelling required column headers (like type, name, label) or using incorrect casing. XLSForm parsers expect specific column names; if they don’t match exactly, the converter will fail or ignore data.
How it happens:
- Typing “Type” instead of “type” or “lable” instead of “label”.
- Adding extra spaces: “ name” or “label “.
Fix:
- Use the exact column headers: type, name, label (all lowercase, no extra spaces).
- Keep a reference checklist or template spreadsheet to copy headers from.
- Consider using validation tools (like the online XLSForm validator) that point out unknown columns.
Example:
- Wrong: “Lable” → Correct: “label”
2 — Invalid question names
Question names (the “name” column) must be unique, start with a letter or underscore, and contain only letters, numbers, and underscores. Spaces and punctuation will break form logic and references.
How it happens:
- Using “Q1 Age” or “age-year” as a name.
- Duplicate names across repeats or groups.
Fix:
- Use snake_case or camelCase (e.g., age_year or ageYear).
- Ensure uniqueness across the whole form.
- Avoid reserved words in some systems (like “instance” or “submission”).
3 — Wrong type declarations
Using an incorrect or unsupported question type will cause conversion or runtime errors. Examples include typos like “integar” or using types that need additional parameters without them (e.g., select_one lists without a choices sheet entry).
How it happens:
- Typo in type name.
- Forgetting to define the choices list for select_one/select_multiple.
Fix:
- Use valid types: text, integer, decimal, select_one
, select_multiple , date, datetime, time, note, calculate, begin_group, end_group, begin_repeat, end_repeat, etc. - Ensure select lists referenced exist in the choices sheet.
Example:
- type: select_one gender — and in choices have list_name “gender” with items.
4 — Misconfigured choices (choices sheet errors)
Common issues in the choices sheet include duplicate list_names, missing list_name entries, duplicate choice names, or missing labels. For select_one and select_multiple to work, choices must be correctly defined.
How it happens:
- Using different list_name spellings (e.g., Gender vs gender).
- Not providing label for a choice or leaving name empty.
Fix:
- Keep list_name consistent and lowercase.
- Ensure each choice row has both name and label.
- Use unique choice names; labels can repeat if needed for display.
5 — Using unsupported or inconsistent bindings in the settings sheet
The settings sheet can include submission_url, form_title, and default language. Mistakes like invalid URLs or inconsistent default language codes cause warnings or broken submissions.
How it happens:
- Typing invalid URLs or using unsupported language codes.
- Changing default language code without updating labels.
Fix:
- Use valid URLs for submission endpoints.
- Keep default language code consistent with label columns (e.g., default language “default” or “en”).
6 — Bad expressions in relevance, calculation, or constraint
XPath expressions used in relevant, constraint, and calculation columns can be fragile. Common errors include wrong field references, missing parentheses, or using arithmetic with text fields.
How it happens:
- Referencing \({age } with a trailing space or wrong name like \){Age}.
- Using functions incorrectly (e.g., concat without commas).
Fix:
- Reference fields exactly: ${field_name}.
- Test expressions in validators or preview tools.
- Use proper functions and ensure types match (convert text to number with number() if needed).
Example:
- Constraint: . >= 0 — instead use ${value} >= 0.
7 — Incorrect use of repeats and groups
Repeats and groups are powerful but easy to misuse. Common issues include forgetting to put child questions inside begin_repeat/end_repeat, misnaming the repeat, or expecting group-level calculations to work like repeat-level calculations.
How it happens:
- Placing begin_repeat without matching end_repeat.
- Trying to reference a repeated child from outside the repeat with a simple ${child}.
Fix:
- Make sure every begin_repeat has a matching end_repeat.
- Understand that references to repeat instances often require indexed-repeat() or aggregate functions.
- Use clear naming and test repeats on a device.
8 — Skipping required columns for advanced features (media, constraints, hints)
Advanced features require specific columns: image/photo types may need media:photo or relevant settings; hints need a hint column; constraint messages require constraint_message.
How it happens:
- Adding a hint text but not creating a hint column.
- Using image without appropriate media settings.
Fix:
- Add the appropriate columns (hint, constraint_message, media::image, etc.).
- Follow the XLSForm spec for namespaced columns (media:photo, body::es for translations).
9 — Localization/translation mistakes
When providing multiple languages, mistakes include unmatched language columns, missing translations for required labels, or wrong default language.
How it happens:
- Having label::en and label::es but setting default language to “fr”.
- Leaving required labels untranslated.
Fix:
- Ensure label columns match the default_language or provide a default label column.
- Keep language suffixes consistent (label::en, hint::en).
- Use the settings sheet default_language to match your label columns.
10 — Saving as the wrong file format
Since XLSForm is an Excel or ODS spreadsheet, saving in the wrong format (like CSV) will destroy structure or multiple sheets. Also, using Excel templates that include strange metadata or protected sheets can cause conversion issues.
How it happens:
- Exporting the spreadsheet to CSV or copying sheets into a plain text editor.
- Using file formats that don’t preserve multiple sheets.
Fix:
- Save as .xlsx or .xls or .ods (preferred .xlsx).
- Keep the survey, choices, and settings sheets as separate tabs.
- Avoid special characters in sheet names.
Quick checklist before converting your XLSForm
- Columns: type, name, label exist and are lowercase.
- Unique names: all question names unique, valid characters only.
- Choices: list_name matches; name and label present.
- Repeats/Groups: begin/end pairs balanced.
- Expressions: references use exact ${name} syntax.
- File: saved as .xlsx/.ods with separate sheets.
Troubleshooting workflow
- Run the XLSForm validator; read the error lines carefully.
- Fix one error at a time, revalidate.
- Test on a device or emulator.
- If using repeats/advanced logic, create a minimal reproduction form to isolate the issue.
This guide covers the common pitfalls that stop an XLSForm from converting or behaving as expected on data-collection platforms. Applying the fixes and checklist above will resolve most problems and make your forms more robust and maintainable.