TheAlgorithms/Java · error · IllegalArgumentException

Invalid binary sequence for single-character tree.

Error message

Invalid binary sequence for single-character tree.

What it means

When the Huffman tree is a single leaf (the corpus contained one distinct character), the code for that character is "0" and decode takes a fast path that asserts every bit is '0'. Any '1' (or other character) in that path is invalid because a single-node tree has no branch to follow, so the library rejects it.

Source

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

     * @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()) {
            return "";
        }
        if (root == null) {
            throw new IllegalStateException("Huffman tree is empty.");
        }

        StringBuilder sb = new StringBuilder();

        if (root.isLeaf()) {
            for (char bit : encodedText.toCharArray()) {
                if (bit != '0') {
                    throw new IllegalArgumentException("Invalid binary sequence for single-character tree.");
                }
                sb.append(root.ch);
            }
            return sb.toString();
        }

        Node current = root;
        for (char bit : encodedText.toCharArray()) {
            if (bit != '0' && bit != '1') {
                throw new IllegalArgumentException("Encoded text contains invalid characters: " + bit);
            }

            current = (bit == '0') ? current.left : current.right;

            if (current.isLeaf()) {
                sb.append(current.ch);
                current = root;
            }

View on GitHub (pinned to fdfb9a395b)

Solutions

1. Ensure every bit in the payload for a single-character tree is '0'.
2. Round-trip test: encode then decode with the same HuffmanCoding instance to catch mismatches.
3. Validate the payload against the tree shape before decoding.

Example fix

// before
HuffmanCoding hc = new HuffmanCoding("aaaa");
String dec = hc.decode("010"); // contains a 1

// after
HuffmanCoding hc = new HuffmanCoding("aaaa");
String dec = hc.decode("000"); // valid single-char-tree payload

// For a single-character tree, every bit must be '0'
if (hc.getHuffmanCodes().size() == 1 && encodedText.chars().anyMatch(b -> b != '0')) {
    throw new IllegalArgumentException("Single-character tree requires all-zero payload");
}
String dec = hc.decode(encodedText);

When it happens

Trigger: Building the tree from a single-character corpus like "aaaa", then decoding a payload containing a '1', e.g. decode("010"); decoding corrupted/mismatched bits against a single-character tree.

Common situations: Encoded payload was tampered with or truncated; the decode corpus differs from the encode corpus (different single character); bits were concatenated incorrectly.

Related errors

• Character '%c' (U+%04X) not found in Huffman dictionary.
• 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/fb333f5084daa6b9. Report an issue: GitHub.