apache/seatunnel · error · MongodbConnectorException

UNSUPPORTED_OPERATION

UNSUPPORTED_OPERATION

Error message

By utilizing flatSyncString, only one field attribute value can be set, and the field type must be a String. This operation will perform a string mapping on a single MongoDB data entry.

What it means

With flatSyncString enabled, the MongoDB deserializer maps each whole BSON document to a single string field, which is only valid when the row schema has exactly one field of type STRING. The check enforces this contract; note the condition uses && so a mismatched multi-field or non-string schema triggers the throw.

Source

Thrown at seatunnel-connectors-v2/connector-mongodb/src/main/java/org/apache/seatunnel/connectors/seatunnel/mongodb/serde/DocumentRowDataDeserializer.java:57

    private final boolean flatSyncString;

    public DocumentRowDataDeserializer(
            String[] fieldNames, SeaTunnelDataType<?> dataTypes, boolean flatSyncString) {
        if (fieldNames == null || fieldNames.length < 1) {
            throw new MongodbConnectorException(ILLEGAL_ARGUMENT, "fieldName is empty");
        }
        this.bsonConverters = new BsonToRowDataConverters();
        this.fieldNames = fieldNames;
        this.fieldTypes = ((SeaTunnelRowType) dataTypes).getFieldTypes();
        this.flatSyncString = flatSyncString;
    }

    @Override
    public SeaTunnelRow deserialize(BsonDocument bsonDocument) {
        if (flatSyncString) {
            if (fieldNames.length != 1 && fieldTypes[0].getSqlType() != STRING) {
                throw new MongodbConnectorException(
                        UNSUPPORTED_OPERATION,
                        "By utilizing flatSyncString, only one field attribute value can be set, and the field type must be a String. This operation will perform a string mapping on a single MongoDB data entry.");
            }
            SeaTunnelRow rowData = new SeaTunnelRow(fieldNames.length);
            rowData.setField(
                    0, bsonConverters.createConverter(fieldTypes[0]).convert(bsonDocument));
            return rowData;
        }
        SeaTunnelRow rowData = new SeaTunnelRow(fieldNames.length);
        for (int i = 0; i < fieldNames.length; i++) {
            String fieldName = this.fieldNames[i];
            BsonValue o = bsonDocument.get(fieldName);
            SeaTunnelDataType<?> fieldType = fieldTypes[i];
            rowData.setField(i, bsonConverters.createConverter(fieldType).convert(o));
        }
        return rowData;
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

  1. When using flatSyncString, declare a schema with exactly one STRING field (e.g. single field 'value' or 'document').
  2. Disable flatSyncString if you need multiple typed columns and define a proper multi-field schema instead.
  3. Ensure the single field's type is STRING (not BYTES/ROW) so the converter serializes the whole document to a string.
  4. Review the connector docs for the flatSyncString contract before enabling it.

Example fix

// before: flatSyncString=true with multi-field schema
fields { id, name } // throws
// after: single STRING field
fields { document } // document: string, compatible with flatSyncString
Defensive patterns

Strategy: validation

Validate before calling

// validate before enabling flatSyncString
boolean valid = rowType.getTotalFields() == 1 && rowType.getFieldType(0).getSqlType() == SqlType.STRING;

Try / catch

try { row = deserializer.deserialize(doc); } catch (MongodbConnectorException e) { if (e.getMessage().contains("flatSyncString")) { log.error("flatSyncString requires exactly one STRING field"); throw new ConfigException(e); } throw e; }

Prevention

When it happens

Trigger: Enabling flatSyncString=true (flat.sync-string option) while the SeaTunnel schema has more than one field, or its single field's SqlType is not STRING; deserialize then validates the contract and throws UNSUPPORTED_OPERATION.

Common situations: Users set flatSyncString to read documents as raw JSON strings but leave a multi-column or non-string schema; copy-pasted config where schema and flatSyncString options conflict; prior version allowed it and a connector update started validating.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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