kestra-io/kestra · error · PebbleException

The argument ''{0}'' is required.

Error message

The argument ''{0}'' is required.

What it means

Thrown by the 'replace' Pebble filter when the required `replace_pairs` argument is null or missing. The filter expects a Map of find→replacement pairs (and an optional boolean `regexp` flag); without the pairs map it cannot perform any substitution.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/filters/ReplaceFilter.java:38

    private static final String ARGUMENT_PAIRS = "replace_pairs";
    private static final String ARGUMENT_REGEXP = "regexp";

    private final static List<String> ARGS = List.of(ARGUMENT_PAIRS, ARGUMENT_REGEXP);

    @Override
    public List<String> getArgumentNames() {
        return ARGS;
    }

    @Override
    @SuppressWarnings("unchecked")
    public Object apply(Object input, Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) throws PebbleException {
        if (input == null) {
            return null;
        }

        if (args.get(ARGUMENT_PAIRS) == null) {
            throw new PebbleException(
                null,
                MessageFormat.format("The argument ''{0}'' is required.", ARGUMENT_PAIRS), lineNumber,
                self.getName()
            );
        }

        final boolean regexp = args.containsKey(ARGUMENT_REGEXP) ? (Boolean) args.get(ARGUMENT_REGEXP) : false;
        Map<?, ?> replacePair = (Map<?, ?>) args.get(ARGUMENT_PAIRS);

        try {
            if (input instanceof Map) {
                return processMap((Map<String, Object>) input, replacePair, regexp);
            } else if (input instanceof List) {
                return processList((List<Object>) input, replacePair, regexp);
            } else {
                return processString(input.toString(), replacePair, regexp);
            }
        } catch (RegexUtils.RegexTimeoutException e) {

View on GitHub (pinned to 823fada927)

Solutions

1. Supply the map: `{{ s | replace(replace_pairs={"a":"b"}) }}`.
2. For literal substitution leave `regexp` off; set `regexp=true` only when keys are regexes.
3. Default dynamic pairs: `replace_pairs=inputs.mappings ?? {}`.

Example fix

# before
{{ msg | replace(regexp=true) }}
# after
{{ msg | replace(replace_pairs={"\\s+":"_"}, regexp=true) }}

# Always pass the replace_pairs map (named exactly):
{{ s | replace(replace_pairs=inputs.mappings ?? {}) }}

{% if inputs.mappings is not null %}
  {{ s | replace(replace_pairs=inputs.mappings) }}
{% endif %}

When it happens

Trigger: Calling `{{ s | replace }}` or `{{ s | replace(regexp=true) }}` without `replace_pairs`; passing a variable for `replace_pairs` that resolved to null; misspelling the argument (e.g. `pairs=` instead of `replace_pairs=`).

Common situations: Confusing the argument name (it is the verbose `replace_pairs`, not `pairs` or `mapping`); referencing an unset input; refactoring drops the argument.

Related errors

• The 'jq' filter expects an argument 'expression'.
• 'keys' filter can only be applied to List, Map, Array. Actua
• The argument 'regex' is required.
• The argument 'regex' is required.
• The argument ''{0}'' is required.

AI-assisted analysis of kestra-io/kestra@823fada927 (2026-08-14). Data as JSON: /api/errors/226c8c5962cebf0d. Report an issue: GitHub.