apache/cassandra · error · ConfigurationException

Failed to validate custom indexer options: ${options}

Error message

Failed to validate custom indexer options: ${options}

What it means

Wraps an unexpected failure thrown by a custom indexer's static validateOptions method. When the reflective InvocationTargetException target is neither InvalidRequestException nor ConfigurationException (e.g. NullPointerException, ClassCastException in plugin code), Cassandra rethrows it as a ConfigurationException that only echoes the options map. It signals the indexer plugin itself crashed during validation, not that a specific option was wrong.

Source

Thrown at src/java/org/apache/cassandra/schema/IndexMetadata.java:199

            {
                unknownOptions = (Map) indexerClass.getMethod("validateOptions", Map.class).invoke(null, filteredOptions);
            }

            if (!unknownOptions.isEmpty())
                throw new ConfigurationException(String.format("Properties specified %s are not understood by %s", unknownOptions.keySet(), indexerClass.getSimpleName()));
        }
        catch (NoSuchMethodException e)
        {
            logger.info("Indexer {} does not have a static validateOptions method. Validation ignored",
                        indexerClass.getName());
        }
        catch (InvocationTargetException e)
        {
            if (e.getTargetException() instanceof InvalidRequestException)
                throw (InvalidRequestException) e.getTargetException();
            if (e.getTargetException() instanceof ConfigurationException)
                throw (ConfigurationException) e.getTargetException();
            throw new ConfigurationException("Failed to validate custom indexer options: " + options);
        }
        catch (ConfigurationException e)
        {
            throw e;
        }
        catch (Exception e)
        {
            throw new ConfigurationException("Failed to validate custom indexer options: " + options);
        }
    }

    public boolean isCustom()
    {
        return kind == Kind.CUSTOM;
    }

    public boolean isKeys()
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check the node/system log around this error for the wrapped cause; the message hides the underlying stack trace.
2. Ensure all options the indexer requires (beyond class_name) are present and of expected types.
3. Fix or replace the indexer plugin; verify plugin compatibility with your Cassandra version.
4. If you maintain the indexer, throw only InvalidRequestException or ConfigurationException so messages propagate correctly.

Example fix

// indexer plugin before
public static Map<String,String> validateOptions(Map<String,String> options) { return check(options.get("required_opt").trim()); } // NPE if absent
// after
public static Map<String,String> validateOptions(Map<String,String> options) { if (!options.containsKey("required_opt")) throw new ConfigurationException("required_opt must be specified"); return check(options.get("required_opt").trim()); }

Map<String,String> copy = new HashMap<>(options); copy.remove("class_name"); // smoke-test the plugin's validateOptions before DDL
Object r = indexerClass.getMethod("validateOptions", Map.class).invoke(null, copy); // throws early if plugin is broken

try { createCustomIndex(cls, options); } catch (ConfigurationException e) { if (e.getMessage().startsWith("Failed to validate custom indexer options")) inspectPluginLogsForCause(); else throw e; }

When it happens

Trigger: CREATE/ALTER CUSTOM INDEX with USING '<class>' + OPTIONS where the indexer's validateOptions(Map) throws an unchecked exception or an exception type other than InvalidRequestException/ConfigurationException; the target exception's cause is swallowed and only the options string is reported.

Common situations: Buggy third-party indexer plugin code (NPE when an expected option is absent), indexer expecting a complex value and calling methods on it that throw, plugin version incompatible with the Cassandra version's validateOptions contract.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• SASI indexes are disabled. Enable in cassandra.yaml to use.
• CUSTOM index requires specifiying the index class
• Cannot specify index class for a non-CUSTOM index
• Invalid comparator class %s: must define a public static ins
• Unable to parse targets for index %s (%s)

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