kestra-io/kestra · error · PebbleException

The 'substringBefore' filter expects an argument 'separator'

Error message

The 'substringBefore' filter expects an argument 'separator'.

What it means

The 'substringBefore' filter returns the portion of a string BEFORE the first occurrence of a separator (StringUtils.substringBefore). It registers 'separator' as a required named argument and throws when apply() is called without it.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/filters/SubstringBeforeFilter.java:33

    private final List<String> argumentNames = new ArrayList<>();

    public SubstringBeforeFilter() {
        this.argumentNames.add("separator");
    }

    @Override
    public List<String> getArgumentNames() {
        return this.argumentNames;
    }

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

        if (!args.containsKey("separator")) {
            throw new PebbleException(
                null,
                "The 'substringBefore' filter expects an argument 'separator'.",
                lineNumber,
                self.getName()
            );
        }

        String separator = (String) args.get("separator");
        ;

        return StringUtils.substringBefore(input.toString(), separator);
    }
}

View on GitHub (pinned to 823fada927)

Solutions

Provide the separator argument explicitly: {{ str | substringBefore(separator="/") }}.
Ensure the separator source variable is defined and non-null before use.
Spell-check the argument name (it must be exactly 'separator').

Example fix

// before
{{ outputs.url | substringBefore }}
// after
{{ outputs.url | substringBefore(separator="://") }}

Defensive patterns

Strategy: validation

Validate before calling

{{ myVar is empty ? '' : myVar | substringBefore(separator=(mySep ?? "/")) }}

Prevention

Always supply the separator named argument.
Guard the separator with a default to avoid an absent binding.
Spell the argument name exactly as 'separator'.

When it happens

Trigger: Calling {{ path | substringBefore }} instead of {{ path | substringBefore(separator="/") }}. Triggered whenever the separator named argument is absent from the args map (undefined variable, typo, or omitted).

Common situations: Stripping a file extension or host from a string and forgetting the separator; separator bound to an optional output that is null; copying a snippet that used a positional separator in a Pebble version that no longer binds it positionally.

Related errors

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