kestra-io/kestra · error · PebbleException

The 'nanoId()' function field 'alphabet' must not be empty

Error message

The 'nanoId()' function field 'alphabet' must not be empty

What it means

The nanoId(length, alphabet) function validates that the custom alphabet, if provided, is non-empty. The default alphabet is 64 URL-safe characters. If a user explicitly passes alphabet='' (empty string), it overrides the default and the resulting char array has length 0, triggering this error. A blank string with content does NOT trigger this because only an empty string produces a zero-length array.

Source

Thrown at core/src/main/java/io/kestra/core/runners/pebble/functions/NanoIDFunction.java:37

    private static final String LENGTH = "length";
    private static final String ALPHABET = "alphabet";

    private static final int MAX_LENGTH = 1000;
    private static final int MAX_ALPHABET_LENGTH = 256;

    @Override
    public Object execute(
        Map<String, Object> args, PebbleTemplate self, EvaluationContext context, int lineNumber) {
        int length = DEFAULT_LENGTH;
        if (args.containsKey(LENGTH) && (args.get(LENGTH) instanceof Long)) {
            length = parseLength(args, self, lineNumber);
        }
        char[] alphabet = DEFAULT_ALPHABET;
        if (args.containsKey(ALPHABET) && (args.get(ALPHABET) instanceof String)) {
            alphabet = ((String) args.get(ALPHABET)).toCharArray();
        }
        if (alphabet.length == 0) {
            throw new PebbleException(
                null,
                "The 'nanoId()' function field 'alphabet' must not be empty",
                lineNumber,
                self.getName()
            );
        }
        if (alphabet.length > MAX_ALPHABET_LENGTH) {
            throw new PebbleException(
                null,
                "The 'nanoId()' function field 'alphabet' must not contain more than: " + MAX_ALPHABET_LENGTH + " characters",
                lineNumber,
                self.getName()
            );
        }
        return createNanoID(length, alphabet);
    }

    private static int parseLength(Map<String, Object> args, PebbleTemplate self, int lineNumber) {

View on GitHub (pinned to 823fada927)

Solutions

1. Provide a non-empty alphabet: {{ nanoId(alphabet='ABCDEF0123456789') }}.
2. If you want the default alphabet, omit the alphabet argument entirely.
3. Ensure any dynamic variable used for the alphabet is never an empty string.

Example fix

# before
value: "{{ nanoId(alphabet='') }}"
# after
value: "{{ nanoId(alphabet='ABCDEF0123456789') }}"

# Ensure alphabet is non-empty, or omit it for the default:
{% if myAlphabet is not empty %}
  {{ nanoId(alphabet=myAlphabet) }}
{% else %}
  {{ nanoId() }}
{% endif %}

When it happens

Trigger: Calling {{ nanoId(alphabet='') }} with an explicitly empty alphabet string. A dynamic variable for the alphabet resolves to an empty string at runtime.

Common situations: The author sets alphabet from a variable that is conditionally populated and is empty in some code path. The author copies a template and forgets to fill in the alphabet value.

Related errors

• The 'nanoId()' function field 'alphabet' must not contain mo
• The 'nanoId()' function field 'length' must be greater than:
• The 'nanoId()' function field 'length' must be lower than: %
• In 'randomIn()' upper is less than lower
• Migration script [<scriptId>] has no checksum to repair.

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