kestra-io/kestra · error · PebbleException

The 'yaml' function expects an argument 'yaml' with type str

Error message

The 'yaml' function expects an argument 'yaml' with type string.

What it means

The `yaml()` function's `yaml` argument must be a `String`. If the argument is present but its runtime type is not `String` (e.g., a Map, List, Number, or Boolean resolved from Pebble), a `PebbleException` is thrown. The function only parses string-serialized YAML.

Source

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

    };

    public List<String> getArgumentNames() {
        return List.of("yaml");
    }

    @Override
    public Map<String, String> getArgumentDefaults() {
        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

Ensure the argument is a raw YAML string, not a pre-parsed object.
If the input is already structured, do not use `yaml()` — use it directly.
If the input is a string-typed flow input containing YAML text, verify it has not been auto-parsed by changing the input type to `STRING`.

Example fix

# before (inputs.yamlInput is type YAML, auto-parsed to a Map)
{{ yaml(inputs.yamlInput) }}
# after (change input type to STRING so it stays raw text)
id: yamlInput
type: STRING

Defensive patterns

Strategy: type-guard

Validate before calling

# Ensure the flow input that feeds yaml() is typed as STRING, not YAML/JSON
id: yamlInput
type: STRING
# Then in template:
{{ yaml(inputs.yamlInput) }}

Type guard

// Type guard: check if value is a string before calling yaml()
function isString(v: unknown): v is string {
    return typeof v === 'string';
}

Prevention

Use STRING input type for content that must be parsed by yaml().
Avoid passing already-parsed YAML/JSON objects to yaml().
If the data is already structured, use it directly without yaml().

When it happens

Trigger: Passing a variable that is already a parsed object (Map/List) rather than a raw YAML string. Passing a numeric or boolean literal.

Common situations: A flow input typed as YAML/JSON is automatically parsed by Kestra before reaching the template, so the variable is already a Map, not a string. The developer expects `yaml()` to handle an already-parsed object.

Related errors

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