chinabugotech/hutool · error · IllegalArgumentException

alphabet must not contain spaces: index %d

Error message

alphabet must not contain spaces: index %d

What it means

Thrown during Hashids construction in validateAndFilterAlphabet() when any character in the custom alphabet is a space character (' '). The space character is reserved and must not appear in the alphabet because it would conflict with the algorithm's internal encoding logic. The error message includes the index of the offending space.

Source

Thrown at hutool-core/src/main/java/cn/hutool/core/codec/Hashids.java:462

	}

	private char[] validateAndFilterAlphabet(final char[] alphabet, final char[] separators) {
		// validate size
		if (alphabet.length < MIN_ALPHABET_LENGTH) {
			throw new IllegalArgumentException(String.format("alphabet must contain at least %d unique " +
					"characters: %d", MIN_ALPHABET_LENGTH, alphabet.length));
		}

		final Set<Character> seen = new LinkedHashSet<>(alphabet.length);
		final Set<Character> invalid = IntStream.range(0, separators.length)
				.mapToObj(idx -> separators[idx])
				.collect(Collectors.toSet());

		// add to seen set (without duplicates)
		IntStream.range(0, alphabet.length)
				.forEach(i -> {
					if (alphabet[i] == ' ') {
						throw new IllegalArgumentException(String.format("alphabet must not contain spaces: " +
								"index %d", i));
					}
					final Character c = alphabet[i];
					if (!invalid.contains(c)) {
						seen.add(c);
					}
				});

		// create a new alphabet without the duplicates
		final char[] uniqueAlphabet = new char[seen.size()];
		int idx = 0;
		for (char c : seen) {
			uniqueAlphabet[idx++] = c;
		}
		return uniqueAlphabet;
	}

	@SuppressWarnings("SameParameterValue")

View on GitHub (pinned to 8870454b2a)

Solutions

1. Remove all space characters from the custom alphabet before passing it to the Hashids constructor.
2. Trim and sanitize configuration-sourced alphabet strings: alphabetStr.replace(" ", "").toCharArray().
3. Use the default DEFAULT_ALPHABET which is guaranteed space-free.

Example fix

// before
char[] alphabet = "abc def ghi jklmnop".toCharArray(); // contains spaces
Hashids h = new Hashids(salt, alphabet, -1); // throws

// after
char[] alphabet = "abcdefghijklmnopqrstuvwxyz0123456789".toCharArray();
Hashids h = new Hashids(salt, alphabet, -1);

String cleaned = new String(alphabet).replace(" ", "");
if (cleaned.length() != alphabet.length) {
    throw new IllegalStateException("Alphabet must not contain spaces");
}

When it happens

Trigger: Calling new Hashids(salt, customAlphabet, minLength) where customAlphabet contains at least one space character at any index. The check iterates every character and throws on the first space found.

Common situations: Building an alphabet from user input or a configuration string that accidentally contains whitespace. Including delimiters or padding characters in the alphabet. Copy-pasting an alphabet string with trailing or embedded spaces.

Related errors

• alphabet must contain at least %d unique characters: %d
• Invalid alphabet for hash
• invalid number: {number}
• invalid hash: {hash}
• Unsupported model:

AI-assisted analysis of chinabugotech/hutool@8870454b2a (2026-08-14). Data as JSON: /api/errors/67ecd5bc21e8c776. Report an issue: GitHub.