apache/cassandra · error · IllegalStateException

a hints file cannot be configured for both compression and…

Error message

a hints file cannot be configured for both compression and encryption

What it means

HintsDescriptor's constructor throws IllegalStateException when an encryption config is present but a compression config is also present. A hints file may be either compressed or encrypted (or plain), not both; the two options are mutually exclusive in the descriptor's parameter space.

Solutions

1. Remove hints_compression from cassandra.yaml when hint encryption is enabled, then restart.
2. Delete or migrate the conflicting hints file (its descriptor parameters cannot be honored).
3. Keep either compression or encryption for hints, not both; encryption provides confidentiality, compression interplay is unsupported.
4. Audit config management templates to ensure the two options are never set together.

Example fix

# before (cassandra.yaml)
hints_compression:
  - class_name: LZ4Compressor
# plus encryption enabled
# after
# hints_compression removed; encryption-only hints config

# validate cassandra.yaml before startup: hints compression XOR encryption
assert not (config.get('hints_compression') and encryption_enabled), \
    "hints_compression and hint encryption are mutually exclusive"

try { HintsDescriptor.deserialize(input); } catch (IllegalStateException e) { logger.error("Hints config conflict: {}", e.getMessage()); }

When it happens

Trigger: Deserializing/constructing a HintsDescriptor from a file name+parameters map (or programmatically) where both 'compression' and 'encryption' parameter entries exist — e.g. hints written by a config that had compression, then encryption was added on top without removing compression settings in cassandra.yaml (hints_compression plus encryption options).

Common situations: Config merge accidents where hints_compression was never removed after enabling hint encryption (企业 encryption-at-rest rollout); upgrading versions where the old compression option lingers in cassandra.yaml; automated config tooling combining both settings.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Binlog is already configured
• cannot load cipher
• commitlog_disk_access_mode =
• Corrupt hint file found
• Corrupt HintsDescriptor serialization, problem:

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

Appendix: source

Thrown at src/java/org/apache/cassandra/hints/HintsDescriptor.java:112

    HintsDescriptor(UUID hostId, int version, long timestamp, ImmutableMap<String, Object> parameters)
    {
        this.hostId = hostId;
        this.version = version;
        this.timestamp = timestamp;
        hintsFileName = hostId + "-" + timestamp + '-' + version + ".hints";
        crc32FileName = hostId + "-" + timestamp + '-' + version + ".crc32";
        compressionConfig = createCompressionConfig(parameters);

        EncryptionData encryption = createEncryption(parameters);
        if (encryption == null)
        {
            cipher = null;
            compressor = null;
        }
        else
        {
            if (compressionConfig != null)
                throw new IllegalStateException("a hints file cannot be configured for both compression and encryption");
            cipher = encryption.cipher;
            compressor = encryption.compressor;
            parameters = encryption.params;
        }

        this.parameters = parameters;
    }

    HintsDescriptor(UUID hostId, long timestamp, ImmutableMap<String, Object> parameters)
    {
        this(hostId, CURRENT_VERSION, timestamp, parameters);
    }

    HintsDescriptor(UUID hostId, long timestamp)
    {
        this(hostId, CURRENT_VERSION, timestamp, ImmutableMap.<String, Object>of());
    }

View on GitHub (pinned to 88fd0f6a0e)