apache/seatunnel · error · MilvusConnectorException

CREATE_INDEX_ERROR

CREATE_INDEX_ERROR

Error message

indexType is required for vector index on column '%s'. Please specify it in schema constraintKeys configuration

What it means

MilvusCatalog.createIndexInternal creates vector indexes from constraintKeys definitions. A VectorIndex without an indexType (e.g. IVF_FLAT, HNSW) cannot be built in Milvus, so it throws MilvusConnectorException with CREATE_INDEX_ERROR telling the user to specify indexType in the schema constraintKeys configuration.

Source

Thrown at seatunnel-connectors-v2/connector-milvus/src/main/java/org/apache/seatunnel/connectors/seatunnel/milvus/catalog/MilvusCatalog.java:240

                    createIndexInternal(tablePath, constraintKey.getColumnNames());
                }
            }
        }
        log.info(
                "Finished creating Milvus collection. database={}, collection={}",
                tablePath.getDatabaseName(),
                tablePath.getTableName());
    }

    private void createIndexInternal(
            TablePath tablePath, List<ConstraintKey.ConstraintKeyColumn> vectorIndexes) {
        for (ConstraintKey.ConstraintKeyColumn column : vectorIndexes) {
            VectorIndex index = (VectorIndex) column;
            String fieldName = index.getColumnName();
            String indexName =
                    StringUtils.isNotBlank(index.getIndexName()) ? index.getIndexName() : fieldName;
            if (index.getIndexType() == null) {
                throw new MilvusConnectorException(
                        MilvusConnectionErrorCode.CREATE_INDEX_ERROR,
                        String.format(
                                "indexType is required for vector index on column '%s'. "
                                        + "Please specify it in schema constraintKeys configuration",
                                fieldName));
            }
            if (index.getMetricType() == null) {
                throw new MilvusConnectorException(
                        MilvusConnectionErrorCode.CREATE_INDEX_ERROR,
                        String.format(
                                "metricType is required for vector index on column '%s'. "
                                        + "Please specify it in schema constraintKeys configuration",
                                fieldName));
            }
            log.info(
                    "Creating Milvus vector index. database={}, collection={}, field={}, indexName={}, indexType={}, metricType={}",
                    tablePath.getDatabaseName(),
                    tablePath.getTableName(),

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add indexType to the VectorIndex definition in schema constraintKeys (e.g. indexType = IVF_FLAT / HNSW / AUTOINDEX).
2. Ensure the index params are provided as a ConstraintKey of type VectorIndex, not a plain column constraint.
3. Consult the Milvus connector docs for the exact constraintKeys syntax and supported index types.
4. Validate the index config locally before running the full pipeline.

Example fix

// before
constraintKeys {
  vector_index {
    columns = ["embedding"]
  }
}
// after
constraintKeys {
  vector_index {
    indexType = "HNSW"
    metricType = "L2"
    columns = ["embedding"]
  }
}

for (ConstraintKey ck : catalogTable.getConstraintKeys()) {
    if (ck instanceof VectorIndex v) {
        if (v.getIndexType() == null) {
            throw new IllegalArgumentException("Vector index on '" + v.getColumnName() + "' missing indexType");
        }
    }
}

boolean hasIndexType(VectorIndex idx) { return idx.getIndexType() != null && !idx.getIndexType().isBlank(); }

try {
    catalog.createTable(tablePath, catalogTable, false);
} catch (MilvusConnectorException e) {
    if (MilvusConnectionErrorCode.CREATE_INDEX_ERROR.equals(e.getSeaTunnelErrorCode())) {
        log.error("Vector index misconfigured: {}", e.getMessage());
    }
    throw e;
}

When it happens

Trigger: createTable -> createIndexInternal encounters a VectorIndex constraint whose getIndexType() == null, i.e. the constraintKeys block for a vector column omitted the index type parameter.

Common situations: Users define constraintKeys for a vector column but only name the column, unaware Milvus requires an explicit index algorithm; configs copied from non-vector examples; schema generated by tools that don't propagate indexType.

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

• DESC_INDEX_ERROR
• Can not find catalog table with factoryId [%s]
• Sparse vector index cannot be negative: %d
• Failed to open catalog %s
• Unsupported action type:

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