apache/cassandra · error · InvalidRequestException

CUSTOM index requires specifiying the index class

Error message

CUSTOM index requires specifiying the index class

What it means

A custom index (`CREATE CUSTOM INDEX ... USING ...`) must name the implementation class via the `USING` clause. `IndexAttributes.validate()` throws InvalidRequestException when `isCustom` is true but `customClass` is null. (Note the message contains a long-standing typo: 'specifiying'.)

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/IndexAttributes.java:51

    private static final String KW_OPTIONS = "options";

    private static final Set<String> keywords = new HashSet<>();
    private static final Set<String> obsoleteKeywords = new HashSet<>();

    public boolean isCustom;
    public String customClass;

    static
    {
        keywords.add(KW_OPTIONS);
    }

    public void validate() throws RequestValidationException
    {
        validate(keywords, obsoleteKeywords);

        if (isCustom && customClass == null)
            throw new InvalidRequestException("CUSTOM index requires specifiying the index class");

        if (!isCustom && customClass != null)
            throw new InvalidRequestException("Cannot specify index class for a non-CUSTOM index");

        if (!isCustom && !properties.isEmpty())
            throw new InvalidRequestException("Cannot specify options for a non-CUSTOM index");

        if (getRawOptions().containsKey(IndexTarget.CUSTOM_INDEX_OPTION_NAME))
            throw new InvalidRequestException(String.format("Cannot specify %s as a CUSTOM option",
                                                            IndexTarget.CUSTOM_INDEX_OPTION_NAME));

        if (getRawOptions().containsKey(IndexTarget.TARGET_OPTION_NAME))
            throw new InvalidRequestException(String.format("Cannot specify %s as a CUSTOM option",
                                                            IndexTarget.TARGET_OPTION_NAME));

    }

    private Map<String, String> getRawOptions() throws SyntaxException

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Add the `USING '<index implementation class>'` clause, e.g. `USING 'org.apache.cassandra.index.sasi.SASIIndex'` or `USING 'StorageAttachedIndex'`.
  2. If a plain (built-in) index was intended, drop the CUSTOM keyword entirely.
  3. Check any option map for the class reference in `class_name` option usage per the intended index implementation.

Example fix

-- before
CREATE CUSTOM INDEX i ON t (col) WITH OPTIONS = {'case_sensitive':'false'};

-- after
CREATE CUSTOM INDEX i ON t (col) USING 'org.apache.cassandra.index.sasi.SASIIndex' WITH OPTIONS = {'case_sensitive':'false'};
Defensive patterns

Strategy: validation

Validate before calling

if (ddl.matches("(?i)CREATE\\s+CUSTOM\\s+INDEX") && !ddl.matches("(?i)USING\\s+'[^']+'"))
    throw new IllegalArgumentException("CUSTOM index requires USING '<class>'");

Try / catch

try { session.execute(ddl); }
catch (InvalidQueryException e) {
  if (e.getMessage().contains("requires specifiying the index class"))
      throw new IllegalArgumentException("add USING '<implementation class>' to the custom index", e);
  throw e;
}

Prevention

When it happens

Trigger: `CREATE CUSTOM INDEX i ON t (col) WITH OPTIONS = {...}` without the `USING '<class>'` clause — the CUSTOM keyword present but no class name supplied.

Common situations: Hand-written DDL missing USING after adding CUSTOM; template scripts where the USING line was deleted; typos so the parser drops the class.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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