apache/seatunnel · error · UnsupportedOperationException

A decoding format must override this method to apply metadat

Error message

A decoding format must override this method to apply metadata keys.

What it means

DeserializationFormat.applyReadableMetadata is a default method that intentionally throws UnsupportedOperationException. A format that can decode records (decoding format) must override it to propagate requested metadata keys into the produced data type; the default exists only for formats that never support metadata.

Source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/table/connector/DeserializationFormat.java:36

package org.apache.seatunnel.api.table.connector;

import org.apache.seatunnel.api.serialization.DeserializationSchema;
import org.apache.seatunnel.api.table.type.SeaTunnelDataType;

import java.util.Collections;
import java.util.List;
import java.util.Map;

public interface DeserializationFormat {

    DeserializationSchema createDeserializationSchema();

    default Map<String, SeaTunnelDataType<?>> listReadableMetadata() {
        return Collections.emptyMap();
    }

    default void applyReadableMetadata(List<String> metadataKeys, SeaTunnelDataType<?> dataType) {
        throw new UnsupportedOperationException(
                "A decoding format must override this method to apply metadata keys.");
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Override applyReadableMetadata in your DeserializationFormat implementation
2. Choose a format that supports the requested metadata keys
3. Remove the metadata keys from the source config if the format cannot supply them

Example fix

// before
class MyFormat implements DeserializationFormat { /* no override */ }
// after
@Override
public void applyReadableMetadata(List<String> metadataKeys, SeaTunnelDataType<?> dataType) {
    // merge metadataKeys into produced row type
}

if (format.listReadableMetadata().isEmpty() && !metadataKeys.isEmpty())
    throw new IllegalArgumentException("Format does not support metadata keys: " + metadataKeys);

boolean supportsMetadata = !format.listReadableMetadata().isEmpty();

try { format.applyReadableMetadata(keys, dataType); } catch (UnsupportedOperationException e) { // fall back: drop metadata keys or switch format
    dataType = dataTypeWithoutMetadata(); }

When it happens

Trigger: A Source using metadata (e.g. via SourceReader with readableMetadata) whose configured format (Factory's DeserializationFormat) did not override applyReadableMetadata — the engine calls the default and fails.

Common situations: Requesting metadata columns (like table name or partition info from Kafka-style connectors) with a format plugin that lacks metadata support, or a custom format implementation missing the override after upgrading the API.

Related errors

• Failed to fetch metadata from Gravitino for metadata: %s
• Not implemented
• Unsupported convert %s to %s
• Unsupported convert ${value.getClass()} to Float, typeDefine
• Unsupported convert ${value.getClass()} to Float

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