apache/cassandra · error · java.lang.IllegalArgumentException

= is invalid

Error message

%s=%d is invalid

What it means

Zstd compression levels in Cassandra are restricted to the range [FAST_COMPRESSION_LEVEL, BEST_COMPRESSION_LEVEL]. validateCompressionLevel throws IllegalArgumentException with this formatted message when the configured 'compression_level' option falls outside that range. It runs when the compression parameters are parsed for a table.

Solutions

1. Set compression_level to a value inside the accepted range (check FAST_COMPRESSION_LEVEL / BEST_COMPRESSION_LEVEL constants in ZstdCompressorBase for your version).
2. Omit compression_level entirely to use the default level if no non-default tuning is needed.
3. Update provisioning/ORM templates that generate the compression option to clamp the level to the valid range.

Example fix

// before
compression = {'class':'ZstdCompressor','compression_level':100}
// after
compression = {'class':'ZstdCompressor','compression_level':3}

int FAST = ZstdCompressorBase.FAST_COMPRESSION_LEVEL;
int BEST = ZstdCompressorBase.BEST_COMPRESSION_LEVEL;
if (level < FAST || level > BEST) throw new IllegalArgumentException("compression_level " + level + " outside [" + FAST + "," + BEST + "]");

try {
    validateCompressionLevel(level);
} catch (IllegalArgumentException e) {
    level = ZstdCompressorBase.DEFAULT_COMPRESSION_LEVEL; // fall back
}

When it happens

Trigger: Issuing CREATE/ALTER TABLE with compression = {'class':'ZstdCompressor','compression_level': N} where N < FAST_COMPRESSION_LEVEL or N > BEST_COMPRESSION_LEVEL (e.g. level 100 or -1000).

Common situations: Copy-pasting raw zstd library levels (zstd CLI accepts 1-22 plus extreme negatives) that exceed Cassandra's allowed bounds; typos like an extra digit; tooling emitting levels from another system's config.

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

• Cannot mix auto and manual DC weights
• Cannot set concurrent_validations greater than…
• Cannot set repair_session_max_tree_depth to which is < 10…
• Cannot set source data center to be local data center, when…
• Commit log flush interval must be positive: %fms

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

Appendix: source

Thrown at src/java/org/apache/cassandra/io/compress/ZstdCompressorBase.java:175

        try
        {
            Zstd.compress(output, input, compressionLevel(), ENABLE_CHECKSUM_FLAG);
        } catch (Exception e)
        {
            throw new IOException("Compression failed", e);
        }
    }

    /**
     * Check if the given compression level is valid. This can be a negative value as well.
     *
     * @param level compression level
     */
    public static void validateCompressionLevel(int level)
    {
        if (level < FAST_COMPRESSION_LEVEL || level > BEST_COMPRESSION_LEVEL)
        {
            throw new IllegalArgumentException(String.format("%s=%d is invalid", COMPRESSION_LEVEL_OPTION_NAME, level));
        }
    }

    /**
     * Get the supplied compression level; otherwise, use the default
     *
     * @param options compression options
     * @return compression level
     */
    public static int getOrDefaultCompressionLevel(Map<String, String> options)
    {
        if (options == null)
            return DEFAULT_COMPRESSION_LEVEL;

        String val = options.get(COMPRESSION_LEVEL_OPTION_NAME);

        if (val == null)
            return DEFAULT_COMPRESSION_LEVEL;

View on GitHub (pinned to 88fd0f6a0e)