apache/cassandra · error · ConfigurationException

(dynamic message from TableParams.validate fail())

Error message

(dynamic message from TableParams.validate fail())

What it means

TableParams.validate reports invalid table option combinations/values via fail(), which throws ConfigurationException with a formatted message. Covers all validation of table properties (caching, compaction, compression, gc_grace_seconds, transactional/autoRepair settings, etc.).

Solutions

1. Read the formatted ConfigurationException message — it names the exact invalid option/value
2. Correct the offending option in the CREATE/ALTER TABLE statement
3. Validate options against the documentation for your Cassandra version
4. Remove conflicting options so only a mutually valid combination remains

Example fix

// before
ALTER TABLE my_ks.t WITH gc_grace_seconds = -100;
// after
ALTER TABLE my_ks.t WITH gc_grace_seconds = 864000;

// Pre-validate option values: e.g.
if (gcGraceSeconds < 0) throw new IllegalArgumentException("gc_grace_seconds must be >= 0");

try { schemaChange(alterTableCql); } catch (ConfigurationException e) { throw new TableConfigException("Invalid table option: " + e.getMessage(), e); }

When it happens

Trigger: Creating or altering a table whose WITH options yield invalid TableParams — e.g. negative gc_grace_seconds, invalid caching keys, contradictory compaction options, or unsupported transactionalMode/autoRepair combinations — reaching the fail(...) call at TableParams.java:267.

Common situations: Typos or wrong value types in WITH table options; copying options between Cassandra versions with different valid ranges; tools generating conflicting option sets; enabling transactional (Accord) mode with incompatible settings.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• ANY ConsistencyLevel is only supported for writes
• Can only unset '" + name + "'
• Cannot add new field
• Cannot set '" + field + "' to negative value"
• Cannot set '" + field + "' to value outside the range…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/schema/TableParams.java:267

                 minIndexInterval,
                 maxIndexInterval);
        }

        if (memtableFlushPeriodInMs < 0)
            fail("%s must be greater than or equal to 0 (got %s)", MEMTABLE_FLUSH_PERIOD_IN_MS, memtableFlushPeriodInMs);

        if (cdc && memtable.factory().writesShouldSkipCommitLog())
            fail("CDC cannot work if writes skip the commit log. Check your memtable configuration.");

        if (transactionalMode.isTestMode() && !CassandraRelevantProperties.ACCORD_ALLOW_TEST_MODES.getBoolean())
            fail("Transactional mode " + transactionalMode + " can't be used if " + CassandraRelevantProperties.ACCORD_ALLOW_TEST_MODES.getKey() + " is not set");

        autoRepair.validate();
    }

    private static void fail(String format, Object... args)
    {
        throw new ConfigurationException(format(format, args));
    }

    @Override
    public boolean equals(Object o)
    {
        if (this == o)
            return true;

        if (!(o instanceof TableParams))
            return false;

        TableParams p = (TableParams) o;

        return comment.equals(p.comment)
            && securityLabel.equals(p.securityLabel)
            && additionalWritePolicy.equals(p.additionalWritePolicy)
            && allowAutoSnapshot == p.allowAutoSnapshot
            && bloomFilterFpChance == p.bloomFilterFpChance

View on GitHub (pinned to 88fd0f6a0e)