apache/seatunnel · error · OptionValidationException

tables_configs[%d]: 'cql' must not be blank

Error message

tables_configs[%d]: 'cql' must not be blank

What it means

This validation error is thrown by CassandraSourceFactory's tables_configs option validator when a table entry in tables_configs has a missing, non-string, or blank (whitespace-only) 'cql' value. Each entry in tables_configs must carry the CQL query used to read rows from Cassandra, so the factory rejects any entry that cannot supply one. It fails fast at config-evaluation time, before any connection is made.

Source

Thrown at seatunnel-connectors-v2/connector-cassandra/src/main/java/org/apache/seatunnel/connectors/seatunnel/cassandra/source/CassandraSourceFactory.java:96

    static class TableConfigsValidator implements ConditionExtension<List<Map<String, Object>>> {

        @Override
        public String description() {
            return "each 'tables_configs' entry must contain a non-blank 'cql'";
        }

        @Override
        public boolean evaluate(ReadonlyConfig config, List<Map<String, Object>> entries)
                throws OptionValidationException {
            if (entries == null || entries.isEmpty()) {
                return true;
            }
            for (int i = 0; i < entries.size(); i++) {
                Map<String, Object> tableConfig = entries.get(i);
                Object cql = tableConfig == null ? null : tableConfig.get(CQL.key());
                if (!(cql instanceof String) || ((String) cql).trim().isEmpty()) {
                    throw new OptionValidationException(
                            "tables_configs[%d]: 'cql' must not be blank", i);
                }
            }
            return true;
        }
    }

    @Override
    public <T, SplitT extends SourceSplit, StateT extends Serializable>
            TableSource<T, SplitT, StateT> createSource(TableSourceFactoryContext context) {
        CassandraParameters cassandraParameters = new CassandraParameters();
        cassandraParameters.buildWithConfig(context.getOptions());
        return () ->
                (SeaTunnelSource<T, SplitT, StateT>)
                        new CassandraSource(cassandraParameters, context.getOptions());
    }

    @Override

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add a non-blank 'cql' string to every entry in tables_configs (e.g. cql = "SELECT id, name FROM keyspace.table")
2. Check the entry index in the message (tables_configs[N]) to find the offending entry in your config file
3. Remove any null/placeholder or whitespace-only cql values
4. Ensure cql is a quoted string in the config format you use (HOCON/JSON), not a number or object

Example fix

// before
tables_configs = [
  { "table-names" = "keyspace.t1", "cql" = "" }
]
// after
tables_configs = [
  { "table-names" = "keyspace.t1", "cql" = "SELECT id, name FROM keyspace.t1" }
]

for (Map<String, Object> t : tablesConfigs) {
    Object cql = t == null ? null : t.get("cql");
    if (!(cql instanceof String) || ((String) cql).trim().isEmpty()) {
        throw new IllegalArgumentException("every tables_configs entry needs a non-blank 'cql'");
    }
}

boolean hasCql(Map<String, Object> t) {
    return t != null && t.get("cql") instanceof String s && !s.trim().isEmpty();
}

When it happens

Trigger: Configuring the Cassandra source with tables_configs where an entry omits 'cql', sets it to null, sets it to a non-string (e.g. number/object via HOCON), or sets it to "" or " ".

Common situations: Copy-pasting a tables_configs template and forgetting to fill in the cql field; quoting/nesting mistakes in HOCON that turn cql into a non-string; trailing whitespace-only placeholder values; defining multiple table entries and leaving one empty.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• '%s' source don't support off-line job.
• The SQL config must contain at least one source table
• The SQL config must contain `INSERT INTO ... SELECT ...` syn
• Table name duplicate: %s
• AmazonDocumentDB option 'uri' must include authentication cr

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/4d9ed777ea323fc6. Report an issue: GitHub.