alibaba/COLA · error · IllegalArgumentException

alphabet must contain between 1 and 255 symbols.

Error message

alphabet must contain between 1 and 255 symbols.

What it means

Argument-validation guard inside NanoIdUtils.randomNanoId: the supplied alphabet has more than 255 unique symbols (or is empty after uniqueness filtering). The generator picks characters by masking a random byte to at most 255 candidate slots, so an alphabet larger than 255 symbols cannot be indexed reliably; this guard rejects it before any id-building loop runs. The input at fault is the caller-provided char[] alphabet.

Source

Thrown at cola-components/cola-component-job/src/main/java/com/alibaba/cola/job/UuidGenerator.java:91

                    StringBuilder idBuilder = new StringBuilder();

                    while(true) {
                        byte[] bytes = new byte[step];
                        random.nextBytes(bytes);

                        for(int i = 0; i < step; ++i) {
                            int alphabetIndex = bytes[i] & mask;
                            if (alphabetIndex < alphabet.length) {
                                idBuilder.append(alphabet[alphabetIndex]);
                                if (idBuilder.length() == size) {
                                    return idBuilder.toString();
                                }
                            }
                        }
                    }
                }
            } else {
                throw new IllegalArgumentException("alphabet must contain between 1 and 255 symbols.");
            }
        }
    }
}

View on GitHub (pinned to 352e1a8675)

Solutions

1. Provide an alphabet of 1-255 unique symbols
2. Trim a too-large alphabet to a safe subset (e.g. 62 alphanumeric chars)
3. Handle empty configured alphabet by falling back to DEFAULT_ALPHABET

Example fix

// before
char[] alphabet = configAlphabet.toCharArray(); // may be empty or >255
// after
char[] alphabet = (configAlphabet == null || configAlphabet.isEmpty() || configAlphabet.length() > 255)
        ? DEFAULT_ALPHABET : configAlphabet.toCharArray();

if (alphabet == null || alphabet.length < 1 || alphabet.length > 255) {
    throw new IllegalArgumentException("alphabet must contain between 1 and 255 symbols");
}

boolean isValidAlphabet(char[] alphabet) {
    return alphabet != null && alphabet.length >= 1 && alphabet.length <= 255;
}

try {
    id = UuidGenerator.randomNanoId(random, alphabet, size);
} catch (IllegalArgumentException e) {
    log.warn("Invalid alphabet, using default: {}", e.getMessage());
    id = UuidGenerator.randomNanoId(random, DEFAULT_ALPHABET, size);
}

When it happens

Trigger: Calling randomNanoId with an empty char[] (length 0) or a char[] of 256+ symbols.

Common situations: Passing a Unicode-heavy custom alphabet with too many symbols; building the alphabet from an empty config string; concatenating alphabets until exceeding 255.

Related errors

• size must be greater than zero.
• random cannot be null.
• alphabet cannot be null.
• EXTENSION_NOT_FOUND
• BizScenario can not be null for extension

AI-assisted analysis of alibaba/COLA@352e1a8675 (2026-09-08). Data as JSON: /api/errors/6847ee80425bf9fe. Report an issue: GitHub.