apache/seatunnel · error · OptionValidationException

tables_configs[ ]: 'schema' must be configured and non-empty

Error message

tables_configs[%d]: 'schema' must be configured and non-empty

What it means

Every tables_configs entry must define a non-empty 'schema' map so the connector can map the entry's Cypher result to a SeaTunnel table. If the entry's schema is missing, not a Map, or an empty Map, the factory throws OptionValidationException with the entry's index.

Solutions

Add a 'schema' block with table and columns to the tables_configs entry at the reported index.
Ensure the schema map contains at least table and columns definitions.
Verify YAML/HOCON indentation so schema is nested inside the entry, not a sibling.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

tables_configs.eachWithIndex { entry, i ->
  if (!(entry.schema instanceof Map) || entry.schema.isEmpty()) {
    throw new IllegalArgumentException("tables_configs[${i}].schema must be a non-empty map")
  }
}

Prevention

Every entry must carry its own schema; do not rely on root-level inheritance.
Include both table and columns in each schema block.
Verify indentation when writing nested HOCON/YAML.

When it happens

Trigger: tables_configs[i] lacking a 'schema' key, or schema present but empty ({}), detected via !(schemaValue instanceof Map) || ((Map) schemaValue).isEmpty().

Common situations: Users assume schema can be inherited from the root-level config (which is in fact rejected); copied examples omit schema; the schema block was accidentally nested at the wrong indentation level.

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/990b31b49a1e788f. 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:211

        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();
                if (!tableIds.add(tableId)) {
                    throw new OptionValidationException(
                            "tables_configs[%d]: duplicate 'schema.table' value '%s'", i, tableId);
                }
            }
            return true;

View on GitHub (pinned to cf67b549a7)