apache/cassandra · error · ConfigurationException

failed to retrieve target column for: %s

Error message

failed to retrieve target column for: %s

What it means

After reading the 'target' option, validateOptions passes the column name to TargetParser.parse, which resolves it against the table schema. When the name does not correspond to any column in the table's metadata, parse returns null and this ConfigurationException is thrown.

Source

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

        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.");

            if (mode.isAnalyzed)
                throw new ConfigurationException("SPARSE mode doesn't support analyzers.");
        }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Correct the 'target' option to the exact column name as defined in the table schema (run DESCRIBE TABLE to check).
  2. Quote the identifier in CQL if it contains mixed case or special characters: {'target': '"FullName"'}.
  3. Ensure the column exists on the target table before creating the index.

Example fix

// before (column is 'email', target misspelled)
WITH OPTIONS = {'target': 'emial', 'mode': 'PREFIX'};
// after
WITH OPTIONS = {'target': 'email', 'mode': 'PREFIX'};
Defensive patterns

Strategy: validation

Validate before calling

// verify target against schema before creating
Row row = session.execute("SELECT column_name FROM system_schema.columns WHERE keyspace_name=? AND table_name=?", ks, table).one();
// or in Java: check metadata.getTable(table).getColumn(targetName) != null before validateOptions

Try / catch

try {
    session.execute(createIndexStmt);
} catch (InvalidQueryException e) {
    if (e.getMessage().startsWith("failed to retrieve target column")) log.error("Unknown SASI target column: {}", e.getMessage());
}

Prevention

When it happens

Trigger: SASIIndex.validateOptions is called with options where options.get("target") is a non-null string that TargetParser.parse cannot resolve to a ColumnMetadata of the given table (unknown column name, wrong case without quotes, or a qualified/aliased name).

Common situations: Typo in the target column name in CREATE CUSTOM INDEX; specifying a column that was dropped or renamed; case mismatch (CQL identifiers are case-sensitive when quoted); pointing the index at a table that does not have the column.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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