apache/seatunnel · error · IllegalArgumentException

schema.constraintKeys

Error message

schema.constraintKeys[%s].constraintColumns[%s] config invalid: %s

What it means

When parsing schema.constraintKeys, each constraint column's vector index options are validated by constructing a VectorIndex. If VectorIndex's constructor rejects the indexType or metricType, this wraps that error in a contextual IllegalArgumentException naming the constraint key, column, and the underlying message — so the invalid config can be located.

Solutions

1. Fix the indexType/metricType values for that column to valid enum values (see inner message and VectorIndex docs)
2. Trim/correct casing of the configured values
3. Remove the constraintKeys entry if vector indexing is not intended for that column

Example fix

// before
constraintKeys = [{ name = idx, constraintColumns = [{ columnName = vec, indexType = IVF_PROXY }] }]
// after
constraintKeys = [{ name = idx, constraintColumns = [{ columnName = vec, indexType = HNSW }] }]

// before parsing config, validate each constraint column's options
Arrays.stream(MetricType.values()).anyMatch(t -> t.name().equalsIgnoreCase(metric));
Arrays.stream(IndexType.values()).anyMatch(t -> t.name().equalsIgnoreCase(indexType));

try { parse(config); } catch (IllegalArgumentException e) { throw new IllegalArgumentException("Invalid constraintKeys config: " + e.getMessage(), e); }

When it happens

Trigger: A config's schema.constraintKeys entry has a column whose vector index_type or metric_type option is not a valid IndexType/MetricType enum value; VectorIndex throws and parseConstraintColumn rewraps it.

Common situations: Typos or wrong casing in indexType/metricType within constraintKeys blocks, configs copied from other vector databases, or version drift where a metric type isn't supported.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• accessId and accesskey must be provided when sts_token is…
• Agent config is not a readable file
• agent.id must be non-empty after resolution.
• At least one sink plugin must be configured.
• At least one source plugin must be configured.

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

Appendix: source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/table/catalog/schema/ReadonlyConfigParser.java:244

                                                            "schema.constraintKeys[%s].constraintColumns.* config need option [columnName], please correct your config first",
                                                            constraintName)));
            if (constraintType == ConstraintKey.ConstraintType.VECTOR_INDEX_KEY) {
                String indexName =
                        constraintColumnConfig
                                .getOptional(ConnectorCommonOptions.VECTOR_INDEX_NAME)
                                .orElse(null);
                String indexType =
                        constraintColumnConfig
                                .getOptional(ConnectorCommonOptions.VECTOR_INDEX_TYPE)
                                .orElse(null);
                String metricType =
                        constraintColumnConfig
                                .getOptional(ConnectorCommonOptions.VECTOR_METRIC_TYPE)
                                .orElse(null);
                try {
                    return new VectorIndex(indexName, columnName, indexType, metricType);
                } catch (IllegalArgumentException exception) {
                    throw new IllegalArgumentException(
                            String.format(
                                    "schema.constraintKeys[%s].constraintColumns[%s] config invalid: %s",
                                    constraintName, columnName, exception.getMessage()),
                            exception);
                }
            }
            ConstraintKey.ColumnSortType columnSortType =
                    constraintColumnConfig.get(
                            ConnectorCommonOptions.CONSTRAINT_KEY_COLUMN_SORT_TYPE);
            return ConstraintKey.ConstraintKeyColumn.of(columnName, columnSortType);
        }
    }

    private static class PrimaryKeyParser
            implements TableSchemaParser.PrimaryKeyParser<ReadonlyConfig> {

        @Override
        public PrimaryKey parse(ReadonlyConfig schemaConfig) {

View on GitHub (pinned to cf67b549a7)