HumanSignal/label-studio · error · ValidationError

Undefined expression, you can use: {add_data_field_examples}

Error message

Undefined expression, you can use: {add_data_field_examples}

What it means

The add_expression dispatcher only knows the commands range, sample, random, choices, and replace; anything else falls into the else branch and raises this ValidationError listing the supported examples. It is the fallback for unrecognized/misspelled expression commands in add/update-column actions.

Source

Thrown at label_studio/data_manager/actions/data_columns.py:314

    elif command == 'random':
        if len(args) != 2:
            raise ValidationError({'value': 'random(min, max) requires two arguments.'})
        minimum, maximum = int(args[0]), int(args[1])

    elif command == 'choices':
        if not 0 < len(args) < 3:
            raise ValidationError({'value': 'choices(values:list, weights:list) requires one or two arguments.'})
        weights = json.loads(args[1]) if len(args) == 2 else None
        choices = json.loads(args[0])

    elif command == 'replace':
        if len(args) != 2:
            raise ValidationError({'value': 'replace(old_value, new_value) requires two arguments.'})
        old_value, new_value = json.loads(args[0]), json.loads(args[1])

    else:
        raise ValidationError('Undefined expression, you can use: ' + add_data_field_examples)

    offset = 0
    task_iterator = iterate_queryset(queryset.only('id', 'data'), chunk_size=settings.UPDATE_COLUMN_BATCH_SIZE)
    for task_batch in batched_iterator(task_iterator, settings.UPDATE_COLUMN_BATCH_SIZE):
        if command == 'range':
            for index, task in enumerate(task_batch):
                task.data[value_name] = start + offset + index
        elif command == 'sample':
            for task in task_batch:
                task.data[value_name] = next(sample_values)
        elif command == 'random':
            for task in task_batch:
                task.data[value_name] = random.randint(minimum, maximum)
        elif command == 'choices':
            for task, selected_value in zip(
                task_batch, random.choices(population=choices, weights=weights, k=len(task_batch))
            ):
                task.data[value_name] = selected_value

View on GitHub (pinned to 0b49e9b539)

Solutions

1. Use one of the supported commands exactly: range, sample, random, choices, replace (all lowercase)
2. Check the API response message, which appends add_data_field_examples listing valid expressions
3. If you need other mutations, perform them in your own preprocessing before uploading tasks instead of via this action

Example fix

// before
{"command": "shuffle", "args": []}
// after
{"command": "sample", "args": []}

const ALLOWED = ['range', 'sample', 'random', 'choices', 'replace'];
if (!ALLOWED.includes(expr.command)) {
  throw new Error(`Unknown expression command: ${expr.command}`);
}

function isKnownCommand(e) { return ['range','sample','random','choices','replace'].includes(e?.command); }

try {
  await dm.addAction({id: 'add_data_field', expression: expr});
} catch (e) {
  if (String(e).startsWith('Undefined expression')) {
    showSupportedCommandsUI();
  } else throw e;
}

When it happens

Trigger: Calling the add-data-field action with an unknown command such as {"command": "shuffle"}, a typo like "sampl", or uppercase "Random"; sending an empty/missing command field.

Common situations: Typos in command names; inventing expressions that exist in other tools but not Label Studio; version drift where a client uses a command from a forked/newer backend; case-sensitivity mistakes.

Related errors

• sample() does not accept arguments.
• random(min, max) requires two arguments.
• choices(values:list, weights:list) requires one or two argum
• replace(old_value, new_value) requires two arguments.
• Can't find '{action_id}' in registered actions

AI-assisted analysis of HumanSignal/label-studio@0b49e9b539 (2026-08-29). Data as JSON: /api/errors/5940f02d93af6abd. Report an issue: GitHub.