apache/seatunnel · error · UnsupportedOperationException

Metrics snapshots are updated through merge semantics rather

Error message

Metrics snapshots are updated through merge semantics rather than putIfAbsent.

What it means

MetricsSnapshotStateStore.putIfAbsent is explicitly unsupported: metrics snapshots are maintained exclusively through merge semantics, so calling putIfAbsent throws UnsupportedOperationException. The interface contract forces callers to use the merge-based update path so concurrent task metric contexts combine correctly instead of first-writer-wins.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/common/statestore/metrics/MetricsSnapshotStateStore.java:85

     * @return {@code true} if a snapshot exists for the task
     */
    @Override
    default boolean containsKey(TaskLocation taskLocation) {
        return get(taskLocation) != null;
    }

    /**
     * Conditional insertion is intentionally not exposed for metrics snapshots because the current
     * engine model treats them as latest-snapshot overwrites.
     *
     * @param taskLocation task location to store
     * @param metricsContext metrics snapshot to store
     * @return never returns normally
     */
    @Override
    default SeaTunnelMetricsContext putIfAbsent(
            TaskLocation taskLocation, SeaTunnelMetricsContext metricsContext) {
        throw new UnsupportedOperationException(
                "Metrics snapshots are updated through merge semantics rather than putIfAbsent.");
    }

    /**
     * Removes all task metrics belonging to a specific pipeline.
     *
     * @param pipelineLocation pipeline location to remove
     */
    void removePipeline(PipelineLocation pipelineLocation);

    /**
     * Checks whether any task snapshot exists for a specific pipeline.
     *
     * @param pipelineLocation pipeline location to check
     * @return {@code true} if any snapshot exists for the pipeline
     */
    boolean containsPipeline(PipelineLocation pipelineLocation);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Replace putIfAbsent calls with the merge-based update method (merge) provided by MetricsSnapshotStateStore
2. If you need create-or-get semantics, perform the merge with your initial context — merge handles first-write and updates uniformly
3. Audit code paths that handle SeaTunnelMetricsContext and ensure none call the generic putIfAbsent
4. If you control the interface, consider whether putIfAbsent should delegate to merge to avoid foot-guns

Example fix

// before
store.putIfAbsent(taskLocation, metricsContext);

// after
store.merge(taskLocation, metricsContext); // merge semantics combine snapshots

if (store instanceof MetricsSnapshotStateStore) {
    // must use merge, not putIfAbsent
}

void safeMetricsUpdate(StateStore store, TaskLocation loc, SeaTunnelMetricsContext ctx) {
    if (store instanceof MetricsSnapshotStateStore) {
        ((MetricsSnapshotStateStore) store).merge(loc, ctx);
    }
}

try {
    store.putIfAbsent(loc, ctx);
} catch (UnsupportedOperationException e) {
    store.merge(loc, ctx); // fall back to required merge semantics
}

When it happens

Trigger: Calling putIfAbsent(taskLocation, metricsContext) on the metrics snapshot state store — typically code written against the generic StateStore interface assuming putIfAbsent semantics apply to metrics contexts.

Common situations: Custom metrics reporting or plugin code reusing the generic state-store API for metrics; porting code from other state stores where putIfAbsent is valid; refactoring that routed metric updates through the wrong method.

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

• Unsupported generics convert
• Unsupported close starting task
• Failed to close auxiliary state store
• Please invoke DeserializationSchema#deserialize(byte[], Coll
• Collect realtime metrics failed

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