What causes "unknown target column" in apache/cassandra?

Add the 'target' option to the index options: {"target": "column_name"} or in CQL: CREATE CUSTOM INDEX ... ON table (column_name) USING 'org.apache.cassandra.index.sasi.SASIIndex' WITH OPTIONS = {...}.

apache/cassandra · error · ConfigurationException

unknown target column

Error message

unknown target column

What it means

SASI indexes require an explicit 'target' option naming the indexed column. validateOptions throws this ConfigurationException when the options map passed at index creation contains no 'target' key, because without it the index has nothing to index.

Source

Thrown at src/java/org/apache/cassandra/index/sasi/SASIIndex.java:161

                toRebuild.put(sstable, (perSSTable = new HashMap<>()));

            perSSTable.put(index.getDefinition(), index);
        }

        CompactionManager.instance.submitIndexBuild(new SASIIndexBuilder(baseCfs, toRebuild));
    }

    /**
     * Called via reflection at {@link IndexMetadata#validateCustomIndexOptions}
     */
    public static Map<String, String> validateOptions(Map<String, String> options, TableMetadata metadata)
    {
        if (!(metadata.partitioner instanceof Murmur3Partitioner))
            throw new ConfigurationException("SASI only supports Murmur3Partitioner.");

        String targetColumn = options.get("target");
        if (targetColumn == null)
            throw new ConfigurationException("unknown target column");

        Pair<ColumnMetadata, IndexTarget.Type> target = TargetParser.parse(metadata, targetColumn);
        if (target == null)
            throw new ConfigurationException("failed to retrieve target column for: " + targetColumn);

        if (target.left.isComplex())
            throw new ConfigurationException("complex columns are not yet supported by SASI");

        if (target.left.isPartitionKey())
            throw new ConfigurationException("partition key columns are not yet supported by SASI");

        IndexMode.validateAnalyzer(options, target.left);

        IndexMode mode = IndexMode.getMode(target.left, options);
        if (mode.mode == Mode.SPARSE)
        {
            if (mode.isLiteral)
                throw new ConfigurationException("SPARSE mode is only supported on non-literal columns.");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Add the 'target' option to the index options: {"target": "column_name"} or in CQL: CREATE CUSTOM INDEX ... ON table (column_name) USING 'org.apache.cassandra.index.sasi.SASIIndex' WITH OPTIONS = {...}.
If using CQL syntax, place the target column in the parenthesized column list of CREATE CUSTOM INDEX — Cassandra populates the 'target' option from it.
Verify the options map passed to validateOptions with a debug print/log before index creation.

Example fix

// before
CREATE CUSTOM INDEX ON users (full_name) USING 'org.apache.cassandra.index.sasi.SASIIndex'
  WITH OPTIONS = {'mode': 'CONTAINS'};
// after
CREATE CUSTOM INDEX ON users (full_name) USING 'org.apache.cassandra.index.sasi.SASIIndex'
  WITH OPTIONS = {'target': 'full_name', 'mode': 'CONTAINS'};

Defensive patterns

Strategy: validation

Validate before calling

// before creating the index
if (indexOptions.get("target") == null)
    throw new IllegalArgumentException("SASI index requires a 'target' option");

Try / catch

try {
    session.execute(createIndexStmt);
} catch (com.datastax.driver.core.exceptions.InvalidQueryException e) {
    if (e.getMessage().contains("unknown target column")) { /* fix options and retry */ }
}

Prevention

Always place the indexed column in the CREATE CUSTOM INDEX column list so Cassandra fills 'target' automatically.
Lint index-definition templates to require the 'target' key for SASI indexes.

When it happens

Trigger: Creating a SASI index via CREATE CUSTOM INDEX ... WITH options where the options map omits 'target', or programmatically calling SASIIndex.validateOptions(metadata, options) with a map lacking entry 'target'.

Common situations: Hand-written CQL CREATE CUSTOM INDEX statements that set analyzer/mode options but forget the target column; tooling generating index options programmatically that misses the required key; copy-pasting SASI options from examples that used an implicit column list.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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