kestra-io/kestra · error · PebbleException

The 'env' function expects an argument 'name'.

Error message

The 'env' function expects an argument 'name'.

What it means

Thrown by the Pebble 'env' template function when the args map does not contain the required 'name' entry (NAME_ARG). The function reads environment variables by name; without a name there is nothing to look up, so getName() rejects the call before touching envs. A separate, earlier branch returns a default value when the variable is present but empty.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/EnvFunction.java:52

        String name = getName(args, self, lineNumber);
        Object defaultValue = args.get(DEFAULT_ARG);
        Object envsVariable = context.getVariable(RunVariables.ENVS);

        if (!(envsVariable instanceof Map<?, ?> envs)) {
            return defaultValue;
        }

        Object value = envs.get(name);
        if (value == null || value.toString().isEmpty()) {
            return defaultValue;
        }

        return value;
    }

    protected String getName(Map<String, Object> args, PebbleTemplate self, int lineNumber) {
        if (!args.containsKey(NAME_ARG)) {
            throw new PebbleException(null, "The 'env' function expects an argument 'name'.", lineNumber, self.getName());
        }

        return (String) args.get(NAME_ARG);
    }
}

View on GitHub (pinned to 823fada927)

Solutions

1. Call env with a literal or expression name: env('MY_VAR') or env(inputs.var_name).
2. If you want a fallback, use the default argument: env('MY_VAR', default='fallback').
3. Make sure any expression used as the name resolves to a non-empty string before the call.

Example fix

# before
host: "{{ env() }}"
# after
host: "{{ env('DATABASE_HOST', default='localhost') }}"

# Ensure the name resolves to a non-empty string before calling env().
# {{ (varName != null and varName is not empty) ? env(varName, default='fallback') : 'fallback' }}

When it happens

Trigger: Calling env() with no arguments, env('') (empty name bound under a different arg key), or env(default='x') with no name. Also hit if the argument is named anything other than 'name'.

Common situations: Typing env() instead of env('VAR_NAME'); passing a variable whose name is computed from an expression that evaluated to empty; mixing up argument order; copying a snippet that omitted the name.

Related errors

• The 'encrypt' function expects two arguments 'key' and 'plai
• The 'fromIon' function expects an argument 'ion'.
• The 'fromJson' function expects an argument 'json'.
• The 'hourOfDay()' function expects a 'date' argument.
• The '%s' filter expects an integer as argument 'amount'.

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