{"record":{"id":"c555c646d11ba319","repo":"chinabugotech/hutool","slug":"alphabet-must-contain-at-least-d-unique-character","errorCode":null,"errorMessage":"alphabet must contain at least %d unique characters: %d","messagePattern":"alphabet must contain at least (.+?) unique characters: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hutool-core/src/main/java/cn/hutool/core/codec/Hashids.java","lineNumber":449,"sourceCode":"\t\tif (salt.length > 0 && spaceLeft > 0) {\n\t\t\tint length = Math.min(salt.length, spaceLeft);\n\t\t\tSystem.arraycopy(salt, 0, newSalt, offset, length);\n\t\t\tspaceLeft -= length;\n\t\t\toffset += length;\n\t\t}\n\t\t// 3. alphabet\n\t\tif (spaceLeft > 0) {\n\t\t\tSystem.arraycopy(alphabet, 0, newSalt, offset, spaceLeft);\n\t\t}\n\n\t\t// shuffle\n\t\treturn shuffle(alphabet, newSalt);\n\t}\n\n\tprivate char[] validateAndFilterAlphabet(final char[] alphabet, final char[] separators) {\n\t\t// validate size\n\t\tif (alphabet.length < MIN_ALPHABET_LENGTH) {\n\t\t\tthrow new IllegalArgumentException(String.format(\"alphabet must contain at least %d unique \" +\n\t\t\t\t\t\"characters: %d\", MIN_ALPHABET_LENGTH, alphabet.length));\n\t\t}\n\n\t\tfinal Set<Character> seen = new LinkedHashSet<>(alphabet.length);\n\t\tfinal Set<Character> invalid = IntStream.range(0, separators.length)\n\t\t\t\t.mapToObj(idx -> separators[idx])\n\t\t\t\t.collect(Collectors.toSet());\n\n\t\t// add to seen set (without duplicates)\n\t\tIntStream.range(0, alphabet.length)\n\t\t\t\t.forEach(i -> {\n\t\t\t\t\tif (alphabet[i] == ' ') {\n\t\t\t\t\t\tthrow new IllegalArgumentException(String.format(\"alphabet must not contain spaces: \" +\n\t\t\t\t\t\t\t\t\"index %d\", i));\n\t\t\t\t\t}\n\t\t\t\t\tfinal Character c = alphabet[i];\n\t\t\t\t\tif (!invalid.contains(c)) {\n\t\t\t\t\t\tseen.add(c);","sourceCodeStart":431,"sourceCodeEnd":467,"githubUrl":"https://github.com/chinabugotech/hutool/blob/8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442/hutool-core/src/main/java/cn/hutool/core/codec/Hashids.java#L431-L467","documentation":"Thrown during Hashids construction in validateAndFilterAlphabet() when the custom alphabet array has fewer than MIN_ALPHABET_LENGTH (16) characters. The Hashids algorithm requires a minimum alphabet size of 16 to function correctly. This is a hard requirement enforced at object creation time, not at encode/decode time.","triggerScenarios":"Calling new Hashids(salt, customAlphabet, minLength) or Hashids.create(salt, customAlphabet, minLength) where customAlphabet has fewer than 16 characters (before deduplication and separator filtering). Note the check uses the raw array length, not the post-deduplication unique count.","commonSituations":"Defining a custom alphabet that is too short for a specialized use case. Accidentally truncating the alphabet array in configuration. Copy-paste errors when defining the alphabet constant.","solutions":["Ensure the custom alphabet array contains at least 16 unique characters.","Use the default DEFAULT_ALPHABET (62 characters) if you do not have a specific requirement for a custom alphabet.","Add a unit test or startup assertion that checks the alphabet length before constructing the Hashids instance."],"exampleFix":"// before\nchar[] alphabet = \"0123456789abcdef\".toCharArray(); // 16 chars — OK\nHashids h = new Hashids(salt, alphabet, -1);\n\nchar[] tooShort = \"0123456789\".toCharArray(); // 10 chars — throws\nHashids h2 = new Hashids(salt, tooShort, -1);\n\n// after — always verify length\nchar[] alphabet = \"0123456789abcdef\".toCharArray();\nif (alphabet.length < 16) throw new IllegalStateException(\"alphabet too short\");\nHashids h = new Hashids(salt, alphabet, -1);","handlingStrategy":"validation","validationCode":"if (alphabet.length < 16) {\n    throw new IllegalStateException(\"Alphabet must have at least 16 characters, got: \" + alphabet.length);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the default DEFAULT_ALPHABET unless you have a specific reason for a custom one.","Add a startup check or unit test validating the alphabet length.","Document the minimum alphabet size requirement in your configuration."],"tags":["hashids","alphabet","construction","configuration","codec"],"backgroundTag":null,"analyzedSha":"8870454b2a0c29cc6ffd31dcf5667c8ceb2fc442","analyzedAt":"2026-08-14T04:01:12.892Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}