apache/seatunnel · error · IllegalArgumentException

Unsupported pending split list value type ${pendingSplit ==

Error message

Unsupported pending split list value type ${pendingSplit == null ? "null" : pendingSplit.getClass().getName()}.

What it means

Thrown by copyPendingSplits when an element inside a pending-splits list from checkpoint state is not a TiDBSourceSplit instance (or is null). The restore code defensively copies the list and enforces element type so later split assignment cannot fail with ClassCastException.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-tidb/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/tidb/source/enumerator/TiDBSourceCheckpointState.java:94

            } else if (value instanceof List) {
                normalizedPendingSplit.put(entry.getKey(), copyPendingSplits((List<?>) value));
            } else if (value == null) {
                normalizedPendingSplit.put(entry.getKey(), new ArrayList<>());
            } else {
                throw new IllegalArgumentException(
                        String.format(
                                "Unsupported pending split value type %s for reader %s.",
                                value.getClass().getName(), entry.getKey()));
            }
        }
        return normalizedPendingSplit;
    }

    private static List<TiDBSourceSplit> copyPendingSplits(List<?> pendingSplits) {
        List<TiDBSourceSplit> copiedPendingSplits = new ArrayList<>();
        for (Object pendingSplit : pendingSplits) {
            if (!(pendingSplit instanceof TiDBSourceSplit)) {
                throw new IllegalArgumentException(
                        String.format(
                                "Unsupported pending split list value type %s.",
                                pendingSplit == null ? "null" : pendingSplit.getClass().getName()));
            }
            copiedPendingSplits.add((TiDBSourceSplit) pendingSplit);
        }
        return copiedPendingSplits;
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Restart from a fresh checkpoint/savepoint compatible with the current connector version
Remove or fix the invalid element in the checkpoint state for the affected reader
Verify no other connector's split objects are being serialized into this job's state
Regenerate pending splits by starting the job without restore state

Example fix

// before: list contains null element
[{"splitId":"tidb-1"}, null]
// after: only TiDBSourceSplit elements
[{"splitId":"tidb-1"}, {"splitId":"tidb-2"}]

Defensive patterns

Strategy: validation

Validate before calling

// Validate list elements before passing to restore
boolean valid = pendingSplits.stream()
    .allMatch(s -> s instanceof TiDBSourceSplit);
if (!valid) throw new IllegalStateException("pendingSplits contains non-TiDBSourceSplit elements");

Type guard

static boolean allSplitsTyped(List<?> pendingSplits) {
    return pendingSplits != null
        && pendingSplits.stream().allMatch(s -> s instanceof TiDBSourceSplit);
}

Try / catch

try {
    state = TiDBSourceCheckpointState.fromCheckpoint(rawState);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unsupported pending split list value type")) {
        LOG.error("Checkpoint state has foreign/null split elements; discard and restart");
    }
    throw e;
}

Prevention

Keep one connector's split objects out of another connector's state
Regenerate state files after connector upgrades
Serialize and deserialize splits only through the connector's own serializer

When it happens

Trigger: Restoring a checkpoint whose pendingSplits list contains null or non-TiDBSourceSplit elements — typically from a state file written by a different connector version or hand-edited state.

Common situations: Version-skewed checkpoint restore; state corruption; mixing split objects from other CDC connectors (e.g. MySQL splits) into a TiDB job state.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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