apache/cassandra · error · IllegalArgumentException

Provided dictionary byte array is null or empty.

Error message

Provided dictionary byte array is null or empty.

What it means

validate() requires the dictionary payload byte array to be non-null and non-empty. An imported dictionary with no bytes cannot be trained-used for compression and would be useless, so it is rejected early.

Source

Thrown at src/java/org/apache/cassandra/db/compression/CompressionDictionaryDetailsTabularData.java:296

         *     <li>kind is not null and there is such {@link org.apache.cassandra.db.compression.CompressionDictionary.Kind}</li>
         *     <li>dictLength is bigger than 0</li>
         *     <li>dictLength has to be equal to dict's length</li>
         *     <li>dictChecksum has to be equal to checksum computed as part of this method</li>
         *     <li>creation date is not null</li>
         * </ul>
         */
        private void validate()
        {
            if (keyspace == null)
                throw new IllegalArgumentException("Keyspace not specified.");
            if (table == null)
                throw new IllegalArgumentException("Table not specified.");
            if (tableId == null)
                throw new IllegalArgumentException("Table id not specified.");
            if (dictId <= 0)
                throw new IllegalArgumentException("Provided dictionary id must be positive but it is '" + dictId + "'.");
            if (dict == null || dict.length == 0)
                throw new IllegalArgumentException("Provided dictionary byte array is null or empty.");
            if (kind == null)
                throw new IllegalArgumentException("Provided kind is null.");

            CompressionDictionary.Kind dictionaryKind;

            try
            {
                dictionaryKind = CompressionDictionary.Kind.valueOf(kind);
            }
            catch (IllegalArgumentException ex)
            {
                throw new IllegalArgumentException("There is no such dictionary kind like '" + kind + "'. Available kinds: " + Arrays.asList(CompressionDictionary.Kind.values()));
            }

            if (dictLength <= 0)
                throw new IllegalArgumentException("Size has to be strictly positive number, it is '" + dictLength + "'.");
            if (dict.length != dictLength)
                throw new IllegalArgumentException("The length of the provided dictionary array (" + dict.length + ") is not equal to provided length value (" + dictLength + ").");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Load the actual dictionary bytes from the file/storage before constructing the data object
  2. Check the dictionary file exists and is non-empty prior to import
  3. Ensure the read code's error paths do not silently produce null/empty arrays

Example fix

// before
byte[] dict = new byte[0]; // never loaded
// after
byte[] dict = Files.readAllBytes(Paths.get(dictionaryFile));
if (dict.length == 0) throw new IOException("Dictionary file is empty: " + dictionaryFile);
Defensive patterns

Strategy: validation

Validate before calling

if (obj.dict == null || obj.dict.length == 0) throw new IllegalArgumentException("dictionary payload must be non-null and non-empty");

Type guard

boolean hasPayload(CompressionDictionaryDataObject o) { return o.dict != null && o.dict.length > 0; }

Try / catch

try { tabularData.fromDataObject(obj); } catch (IllegalArgumentException e) { if (e.getMessage().contains("dictionary byte array is null or empty")) { /* reload the dictionary bytes from disk */ } else throw e; }

Prevention

When it happens

Trigger: Passing dict == null or a zero-length byte[] into CompressionDictionaryDataObject — e.g. the dictionary file failed to be read, or the caller built the descriptor without loading the dictionary contents.

Common situations: Import tooling that read an empty/missing dictionary file; I/O errors swallowed upstream so the byte array stayed null; truncation that produced an empty buffer.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/ce2b44ea8a6bed8b. Report an issue: GitHub.