What causes "Invalid yaml: %s" in kestra-io/kestra?

Validate the YAML string in an external linter before passing it to the function.

kestra-io/kestra · error · PebbleException

Invalid yaml: %s

Error message

Invalid yaml: %s

What it means

The `yaml()` function delegates to Jackson's YAML parser (`ObjectMapper.readValue`). If the input string is not valid YAML, the parser throws `JacksonYAMLParseException`, `JsonMappingException`, or `JsonProcessingException`, all of which are caught and re-thrown as a `PebbleException` with the prefix 'Invalid yaml:'. The original parser error message is appended.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/YamlFunction.java:49

        return Map.of("yaml", "inputs.yamlInput");
    }

    @Override
    public Object execute(Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) {
        if (!args.containsKey("yaml")) {
            throw new PebbleException(null, "The 'yaml' function expects an argument 'yaml'.", lineNumber, self.getName());
        }

        if (!(args.get("yaml") instanceof String)) {
            throw new PebbleException(null, "The 'yaml' function expects an argument 'yaml' with type string.", lineNumber, self.getName());
        }

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

        try {
            return MAPPER.readValue(yaml, TYPE_REFERENCE);
        } catch (JacksonYAMLParseException e) {
            throw new PebbleException(null, "Invalid yaml: " + e.getMessage(), lineNumber, self.getName());
        } catch (JsonMappingException e) {
            throw new PebbleException(null, "Invalid yaml: " + e.getMessage(), lineNumber, self.getName());
        } catch (JsonProcessingException e) {
            throw new PebbleException(null, "Invalid yaml: " + e.getMessage(), lineNumber, self.getName());
        }
    }
}

View on GitHub (pinned to 823fada927)

Solutions

Validate the YAML string in an external linter before passing it to the function.
Check indentation: YAML requires spaces, never tabs, and consistent indent levels.
Quote scalar values containing special characters (`:`, `{`, `[`, `#`, etc.).
Use the error message's line reference (when available) to locate the syntax issue.

Example fix

# before
{{ yaml(inputs.yamlInput) }}
# where inputs.yamlInput contains:
# key1: value1
# 	key2: value2   <- tab character
# after (fix indentation to spaces)
# key1: value1
# key2: value2

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-validate YAML with Jackson before passing to Pebble template
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;

ObjectMapper yamlMapper = new ObjectMapper(new YAMLFactory());
public static boolean isValidYaml(String input) {
    try {
        yamlMapper.readTree(input);
        return true;
    } catch (Exception e) {
        return false;
    }
}

Try / catch

// In Java code that builds templates with dynamic YAML
try {
    String result = pebbleTemplate.evaluate(context);
} catch (PebbleException e) {
    if (e.getMessage().startsWith("Invalid yaml:")) {
        log.warn("YAML parsing failed in template: {}", e.getMessage());
        // provide fallback or user-facing error
    } else {
        throw e;
    }
}

Prevention

Validate YAML content with an external linter before storing it in a variable.
Never use tabs for YAML indentation — always use spaces.
Quote scalars that contain special characters (:, #, {, }, [, ]).
Test multi-line YAML inputs in isolation before embedding them in a flow.

When it happens

Trigger: Passing a YAML string with malformed syntax: wrong indentation, unbalanced brackets, tab characters, or unquoted special characters. Passing content that is valid in one format but not YAML (e.g., raw JSON with comments).

Common situations: A user concatenates YAML fragments with string operations that introduce whitespace or indentation errors. Tabs are used instead of spaces for indentation. A multi-line input field contains stray characters.

Related errors

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