TheAlgorithms/Java · error · IllegalArgumentException

Character '%c' (U+%04X) not found in Huffman dictionary.

Error message

Character '%c' (U+%04X) not found in Huffman dictionary.

What it means

HuffmanCoding.encode iterates each character of the input and looks it up in the huffmanCodes map built from the training corpus. If a character was never seen when the tree was constructed, it has no code and cannot be encoded — the library rejects it rather than silently dropping or mis-encoding the character.

Source

Thrown at src/main/java/com/thealgorithms/compression/HuffmanCoding.java:186

     * @param text The plaintext string to compress.
     * @return A string of '0's and '1's representing the compressed data.
     * Returns an empty string if the input is null or empty.
     * @throws IllegalStateException    If attempting to encode when the Huffman tree is empty.
     * @throws IllegalArgumentException If the input text contains a character not present
     * in the original text used to build the tree.
     */
    public String encode(String text) {
        if (text == null || text.isEmpty()) {
            return "";
        }
        if (root == null) {
            throw new IllegalStateException("Huffman tree is empty.");
        }

        StringBuilder sb = new StringBuilder();
        for (char c : text.toCharArray()) {
            if (!huffmanCodes.containsKey(c)) {
                throw new IllegalArgumentException(String.format("Character '%c' (U+%04X) not found in Huffman dictionary.", c, (int) c));
            }
            sb.append(huffmanCodes.get(c));
        }
        return sb.toString();
    }

    /**
     * Decodes the given binary string back into the original plaintext using the Huffman Tree.
     * Validates the integrity of the binary payload during traversal.
     *
     * @param encodedText The binary string of '0's and '1's to decompress.
     * @return The reconstructed plaintext string. Returns an empty string if the input is null or empty.
     * @throws IllegalStateException    If attempting to decode when the Huffman tree is empty.
     * @throws IllegalArgumentException If the binary string contains characters other than '0' or '1',
     * or if the sequence ends abruptly without reaching a leaf node.
     */
    public String decode(String encodedText) {
        if (encodedText == null || encodedText.isEmpty()) {

View on GitHub (pinned to fdfb9a395b)

Solutions

1. Rebuild the Huffman tree from a corpus that includes every character you intend to encode.
2. Validate that every character in the input is present in getHuffmanCodes() before encoding.
3. Normalize input (e.g. casing) to match the corpus alphabet.

Example fix

// before
HuffmanCoding hc = new HuffmanCoding("aabb");
String enc = hc.encode("aabc"); // c not in tree

// after
HuffmanCoding hc = new HuffmanCoding(corpus); // corpus includes c
for (char ch : message.toCharArray()) {
    if (!hc.getHuffmanCodes().containsKey(ch)) {
        throw new IllegalArgumentException("Character " + ch + " absent from Huffman dictionary");
    }
}
String enc = hc.encode(message);

Map<Character, String> codes = hc.getHuffmanCodes();
for (char c : text.toCharArray()) {
    if (!codes.containsKey(c)) {
        throw new IllegalArgumentException("Character " + c + " not in Huffman dictionary; rebuild tree from a fuller corpus");
    }
}
String enc = hc.encode(text);

When it happens

Trigger: Building the tree from "aabb" then calling encode("aabc") (c is unknown); encoding text whose alphabet differs from the training corpus; encoding after the corpus was a strict subset.

Common situations: Training corpus did not cover all characters that appear in production data; a new/edge-case character appears at runtime; case mismatch (tree built on lowercase, encode given uppercase).

Related errors

• Invalid binary sequence for single-character tree.
• Encoded text contains invalid characters: {}
• Malformed encoded string: incomplete sequence ending.
• Input string cannot be null or empty.
• Original index must be between 0 and {}, got: {}

AI-assisted analysis of TheAlgorithms/Java@fdfb9a395b (2026-08-13). Data as JSON: /api/errors/b21adafb2b5317e2. Report an issue: GitHub.