apache/seatunnel · error · HugeGraphConnectorException

INVALID_GRAPH_SCHEMA

INVALID_GRAPH_SCHEMA

Error message

Mapping[VERTEX/%s]: Field '%s' specified in idFields not found in row schema. Available fields: %s

What it means

A field listed in the mapping's idFields does not exist in the incoming SeaTunnelRow's schema, so the connector cannot locate the column index used to read the id value. Thrown as INVALID_GRAPH_SCHEMA from getFieldValues, which resolves each id field name against the row's field index built from the CatalogTable.

Source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/mapper/VertexMapper.java:307

                Object uuidValue = uuidValues.get(0);
                if (isConsideredNull(uuidValue)) {
                    return null;
                }
                return UUID.fromString(String.valueOf(uuidValue));
            default:
                throw new HugeGraphConnectorException(
                        HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT,
                        "Unsupported IdStrategy: " + strategy);
        }
    }

    private List<Object> getFieldValues(SeaTunnelRow row, List<String> fields) {
        List<Object> values = new ArrayList<>(fields.size());
        Map<String, String> fm = mappingConfig.getFieldMapping();
        for (String fieldName : fields) {
            Integer index = fieldsIndex.get(fieldName);
            if (index == null) {
                throw new HugeGraphConnectorException(
                        HugeGraphConnectorErrorCode.INVALID_GRAPH_SCHEMA,
                        String.format(
                                "Mapping[VERTEX/%s]: Field '%s' specified in idFields not found in row schema. "
                                        + "Available fields: %s",
                                mappingConfig.getLabel(), fieldName, fieldsIndex.keySet()));
            }

            Object rawValue = row.getField(index);
            if (isConsideredNull(rawValue)) {
                continue;
            }

            String propName = fm.getOrDefault(fieldName, fieldName);
            PropertyKey propertyKey = propertyKeyCache.get(propName);

            Object converted = rawValue;
            if (propertyKey != null) {
                converted =

View on GitHub (pinned to cf67b549a7)

Solutions

1. Correct the id_fields entry in the sink mapping to match the actual upstream column name exactly.
2. Add the missing column back upstream (e.g. in the source query or a SQL transform) before the HugeGraph sink.
3. Print/inspect the CatalogTable columns reaching the sink and align field_mapping and id_fields with them.

Example fix

// before
"id_fields": ["usr_id"]   // upstream column is user_id
// after
"id_fields": ["user_id"]

Set<String> schemaFields = catalogTable.getTableSchema().getFieldNames();
for (String f : mapping.getIdFields()) {
    if (!schemaFields.contains(f)) throw new IllegalArgumentException("id field not in schema: " + f);
}

When it happens

Trigger: getFieldValues is called (from pkValues/stringValues/numberValues/uuidValues during extractId) and fieldsIndex.get(fieldName) returns null because the idFields name does not match any column in the row schema.

Common situations: Typo in id_fields config; upstream Source/Transform renamed or dropped the column; SQL transform projects fewer columns than the sink mapping expects; case-sensitivity mismatch between config and schema.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• HugeGraphConnectorErrorCode.INVALID_GRAPH_SCHEMA
• INVALID_CONFIG
• ILLEGAL_CONFIG_ARGUMENT
• INVALID_GRAPH_SCHEMA
• INVALID_GRAPH_SCHEMA

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