apache/seatunnel · error · OptionValidationException

tables_configs[ ]: 'query' must be configured and non-blank

Error message

tables_configs[%d]: 'query' must be configured and non-blank

What it means

Each entry in 'tables_configs' must contain a non-blank 'query' (Cypher) string. The factory reads the entry map by the KEY_QUERY option key and throws OptionValidationException if the value is missing, not a String, or blank after trimming. Validation happens at config-parse time, before any connection is made.

Solutions

  1. Add a valid Cypher 'query' string to every tables_configs entry.
  2. Check the option key spelling is exactly 'query' inside the entry map.
  3. Trim or replace blank query values with the actual Cypher statement.

Example fix

// before
tables_configs = [
  { schema = { table = "person", ... } }
]
// after
tables_configs = [
  { query = "MATCH (n:Person) RETURN n.name AS name", schema = { table = "person", ... } }
]
Defensive patterns

Strategy: validation

Validate before calling

tables_configs.eachWithIndex { entry, i ->
  if (!(entry.query instanceof String) || entry.query.trim().isEmpty()) {
    throw new IllegalArgumentException("tables_configs[${i}].query must be a non-blank Cypher string")
  }
}

Prevention

When it happens

Trigger: tables_configs entry where 'query' is absent, set to a non-string value, empty string, or whitespace-only (entry.get(Neo4jSourceOptions.KEY_QUERY.key()) fails the instanceof String / trim().isEmpty() check).

Common situations: Typos like 'qurey' or 'queries' instead of 'query'; YAML/HOCON indentation placing query outside the entry; leaving a placeholder empty query when generating multi-table configs.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-neo4j/src/main/java/org/apache/seatunnel/connectors/seatunnel/neo4j/source/Neo4jSourceFactory.java:205

        @Override
        public String description() {
            return "each 'tables_configs' entry must contain a non-blank 'query' and a schema with a unique 'table'";
        }

        @Override
        public boolean evaluate(ReadonlyConfig config, List<Map<String, Object>> entries)
                throws OptionValidationException {
            if (config.getOptional(ConnectorCommonOptions.SCHEMA).isPresent()) {
                throw new OptionValidationException(
                        "root-level 'schema' cannot be used with 'tables_configs'");
            }

            Set<String> tableIds = new HashSet<>();
            for (int i = 0; i < entries.size(); i++) {
                Map<String, Object> entry = entries.get(i);
                Object query = entry.get(Neo4jSourceOptions.KEY_QUERY.key());
                if (!(query instanceof String) || ((String) query).trim().isEmpty()) {
                    throw new OptionValidationException(
                            "tables_configs[%d]: 'query' must be configured and non-blank", i);
                }

                Object schemaValue = entry.get(ConnectorCommonOptions.SCHEMA.key());
                if (!(schemaValue instanceof Map) || ((Map<?, ?>) schemaValue).isEmpty()) {
                    throw new OptionValidationException(
                            "tables_configs[%d]: 'schema' must be configured and non-empty", i);
                }

                Object tableValue =
                        ((Map<?, ?>) schemaValue).get(ConnectorCommonOptions.TABLE.key());
                if (!(tableValue instanceof String) || ((String) tableValue).trim().isEmpty()) {
                    throw new OptionValidationException(
                            "tables_configs[%d]: 'schema.table' must be configured and non-blank",
                            i);
                }

                String tableId = ((String) tableValue).trim();

View on GitHub (pinned to cf67b549a7)