Validation & Errors

Validation errors render in the question-local error area below the comment. Empty error containers must not consume layout height.

Validation tag

<question type="single" name="Q1" required>
  <description>Choose one option.</description>
  <options>
    <option value="1">One</option>
    <option value="2">Two</option>
  </options>
  <validation>
    if ($curr.o1) {
      hardError("Option 1 is not allowed.");
    }
  </validation>
</question>

hardError(message) blocks progress. softError(message) shows a one-time question-local message. Duplicate messages are normalized and rendered once.

Error message catalog

Survey Link uses an English default error catalog for built-in respondent validation and authored <validation> code. The catalog is exposed as $errorMessages in validation code.

hardError($errorMessages.minSelect, { min: 3 })
softError($errorMessages.maxRank, { max: 5 })
hardError("Choose {need} more option(s).", { need: 2 })

hardError(messageOrDescriptor, params?) blocks progress. softError(messageOrDescriptor, params?) renders a one-time question-local message. {param} placeholders are replaced before duplicate messages are normalized and rendered once.

Common catalog keys include:

Custom HTML controls

Mixed DSL + Custom HTML renders in the normal React Survey Link flow. Consecutive raw HTML fragments between DSL blocks are page-scoped custom blocks. Native input, select, and textarea values are captured by their name attributes.

<question type="single" name="Q1">
  <description>Choose one.</description>
  <option value="1">One</option>
</question>
 
<div class="custom-note">
  <label>Explain briefly
    <textarea name="RAW_EXPLAIN" required minlength="5"></textarea>
  </label>
</div>
 
<divider />

Do not wrap survey content in a <form> tag. Vibe Survey owns the respondent form runtime. Native HTML validation attributes such as required, min, max, minlength, and pattern block Next/Complete and render custom-block-local errors.

TEST Audit Mode

TEST links include an Audit Mode toggle in Runtime Tools. Audit Mode displays compact metadata for QA, including question names, question type, option codes, attribute codes, group names, and semantic left/right labels. Option/attribute/group/left/right codes render as inline prefixes before the label, not as separate badges, so the respondent layout remains inspectable. Dense settings such as min/max/step/order/mode/display-style are available through the custom metadata hovercard. LIVE links never render Audit Mode UI.

Template Expression diagnostics

Template Expression runtime errors are reported as template-expression console entries in TEST links. Repeated identical errors are deduplicated by source/question/message so a broken expression does not flood the console or Run generate result.

Dynamic attribute fallback is logged when an evaluated attribute would make the question impossible to answer. For example, if a dynamic number min becomes greater than max, Survey Link drops the conflicting bound for that render and keeps the respondent flow available. Run generate reports the same fallback once in diagnostics.