apache/cassandra · error · IllegalArgumentException

Provided dictionary id must be positive but it is '<dictId>'

Error message

Provided dictionary id must be positive but it is '<dictId>'.

What it means

The dictionary id must be a strictly positive integer; validate() rejects dictId <= 0 and includes the offending value in the message. Dictionary ids are assigned by Cassandra and used as the unique identifier of the dictionary, so zero or negative values are invalid by contract.

Source

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

         *     <li>dict is not null nor empty</li>
         *     <li>dict length is less than or equal to 1MiB</li>
         *     <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 + "'.");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Supply the real positive dictionary id (as reported by LIST COMPRESSION DICTIONARIES or the JMX interface)
  2. If the id is unknown, fetch it from the system.compression_dict table instead of guessing
  3. Check that the numeric field has been initialized, not left at its 0 default

Example fix

// before
long dictId = 0; // unset default
// after
long dictId = existingDictionary.id().asLong(); // positive id from the stored dictionary
Defensive patterns

Strategy: validation

Validate before calling

if (obj.dictId <= 0) throw new IllegalArgumentException("dictId must be positive, got: " + obj.dictId);

Type guard

boolean hasPositiveDictId(CompressionDictionaryDataObject o) { return o.dictId > 0; }

Try / catch

try { tabularData.fromDataObject(obj); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Provided dictionary id must be positive")) { /* fetch the real id from system.compression_dict */ } else throw e; }

Prevention

When it happens

Trigger: Constructing a CompressionDictionaryDataObject with dictId set to 0, a negative number, or an unset/zero-initialized numeric field (e.g. a Java long/int field defaulted to 0).

Common situations: Hand-built descriptors where the id was never populated (defaulting to 0); parsing errors that yield 0; callers confusing an index (0-based) with a dictionary id (positive).

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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