apache/cassandra · error · IllegalArgumentException

Only single character delimiters supported, was %s

Error message

Only single character delimiters supported, was %s

What it means

SASI's DelimiterTokenizingOptions requires the 'delimiter' option to be exactly one character, because the analyzer stores it as a Java char. When buildFromMap reads the DELIMITER entry from the options map and the string is empty or longer than one character, it throws this IllegalArgumentException.

Source

Thrown at src/java/org/apache/cassandra/index/sasi/analyzer/DelimiterTokenizingOptions.java:62

        public DelimiterTokenizingOptions build()
        {
            return new DelimiterTokenizingOptions(delimiter);
        }
    }

    static DelimiterTokenizingOptions buildFromMap(Map<String, String> optionsMap)
    {
        OptionsBuilder optionsBuilder = new OptionsBuilder();

        for (Map.Entry<String, String> entry : optionsMap.entrySet())
        {
            switch (entry.getKey())
            {
                case DELIMITER:
                {
                    String value = entry.getValue();
                    if (1 != value.length())
                        throw new IllegalArgumentException(String.format("Only single character delimiters supported, was %s", value));

                    optionsBuilder.delimiter = entry.getValue().charAt(0);
                    break;
                }
            }
        }
        return optionsBuilder.build();
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Pass a single-character delimiter string, e.g. 'delimiter': ','
2. Use a one-char proxy (e.g. ';' instead of '; ') and strip whitespace in a custom analyzer
3. Empty string: omit the delimiter option entirely or use a single non-delimiter placeholder char

Example fix

// before
'options': {'analyzer_class': 'DelimiterAnalyzer', 'delimiter': ', '}
// after
'options': {'analyzer_class': 'DelimiterAnalyzer', 'delimiter': ','}

String delim = options.get("delimiter");
if (delim != null && delim.length() != 1) throw new IllegalArgumentException("delimiter must be a single character, was: " + delim);

try { createIndex(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Only single character delimiters")) { options.put("delimiter", options.get("delimiter").substring(0,1)); createIndex(options); } else throw e; }

When it happens

Trigger: Creating a SASI index with an analyzer whose options map contains 'delimiter' set to a multi-character string (e.g. '||', ', ') or an empty string ''.

Common situations: Users specifying a multi-character separator like ', ' or '||' in CREATE CUSTOM INDEX OPTIONS, or templating that leaves delimiter empty.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Empty value for boolean option ''
• Illegal value for boolean option '':
• case_sensitive option cannot be specified together with eith
• minTokenLength must be greater than zero
• maxTokenLength must be greater than zero

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