apache/seatunnel · error · OptionValidationException

tables_configs[ ]: 'schema.table' must be configured and…

Error message

tables_configs[%d]: 'schema.table' must be configured and non-blank

What it means

Within a tables_configs entry, the 'schema' block must include a non-blank 'table' (table name). The factory extracts ConnectorCommonOptions.TABLE from the schema map and throws OptionValidationException when it is missing, not a String, or blank after trimming.

Solutions

Set schema.table to a non-blank table name in the entry at the reported index.
Confirm the key name matches ConnectorCommonOptions.TABLE ('table').
Check that variable substitution in the config yields a real table name, not an empty string.

Example fix

// before
schema = { columns = [{ name = name, type = string }] }
// after
schema = {
  table = "person"
  columns = [{ name = name, type = string }]
}

Defensive patterns

Strategy: validation

Validate before calling

tables_configs.eachWithIndex { entry, i ->
  def t = entry.schema?.table
  if (!(t instanceof String) || t.trim().isEmpty()) {
    throw new IllegalArgumentException("tables_configs[${i}].schema.table must be non-blank")
  }
}

Prevention

Always set schema.table alongside columns.
Use the exact key name 'table' as defined by ConnectorCommonOptions.
Resolve template variables before submitting the job.

When it happens

Trigger: tables_configs[i].schema exists but has no 'table' key, an empty/whitespace table value, or a non-string table value.

Common situations: Users define only columns in schema and forget table_name; the table key is misspelled (e.g. 'table_name' vs 'table' depending on option definition); template variables left unresolved produce empty strings.

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/394f446088bba6c8. 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:218

            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)