apache/seatunnel · error · IllegalArgumentException

Google Pub/Sub source expects exactly one source split

Error message

Google Pub/Sub source expects exactly one source split

What it means

Thrown from GooglePubSubSourceReader.addSplits when the engine hands the reader a list of source splits whose size is not exactly one. Pub/Sub subscriptions are a single logical stream, so the connector enumerates exactly one SingleSplit; any other number violates the connector's invariant.

Solutions

1. Ensure restore state comes from a checkpoint of the same GooglePubSub source version and configuration.
2. In tests or custom code, always pass a list containing exactly one split (as produced by the split enumerator).
3. If migrating from an older connector version, start the job fresh rather than restoring incompatible state.

Example fix

// before
reader.addSplits(Collections.emptyList());
// after
reader.addSplits(Collections.singletonList(new SingleSplit(null)));

if (splits == null || splits.size() != 1) {
    throw new IllegalArgumentException("Pass exactly one split to GooglePubSubSourceReader");
}

try {
    reader.addSplits(splits);
} catch (IllegalArgumentException e) {
    logger.error("Split invariant violated for Pub/Sub reader", e);
    throw e;
}

When it happens

Trigger: addSplits(list) called (via assignSplit) with an empty list or more than one split — typically only possible through custom/test code or an engine/restore path that reassigns snapshots taken from a differently-shaped source.

Common situations: Restoring from a checkpoint/savepoint produced by another connector or a modified split enumeration; unit or integration tests feeding synthetic split lists; parallelism/split mishandling in custom engine integrations.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• ACKNOWLEDGE_FAILED
• CONFIGURATION_FAILED
• CONNECTION_FAILED
• Failed to close Google Pub/Sub publisher
• Option 'field_delimiter' cannot be empty

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-google-pubsub/src/main/java/org/apache/seatunnel/connectors/seatunnel/google/pubsub/source/GooglePubSubSourceReader.java:133

                        "Failed to deserialize Google Pub/Sub message "
                                + receivedMessage.message.getMessageId(),
                        e);
            }
        }
    }

    @Override
    public List<SingleSplit> snapshotState(long checkpointId) {
        synchronized (acknowledgementLock) {
            pendingAcknowledgements.put(checkpointId, new ArrayList<>(unacknowledgedMessages));
        }
        return Collections.singletonList(new SingleSplit(null));
    }

    @Override
    public void addSplits(List<SingleSplit> splits) {
        if (splits.size() != 1) {
            throw new IllegalArgumentException(
                    "Google Pub/Sub source expects exactly one source split");
        }
        if (splitAssigned) {
            return;
        }

        subscriber =
                subscriberFactory.create(
                        (message, acknowledgement) ->
                                receivedMessages.add(new ReceivedMessage(message, acknowledgement)),
                        failure -> subscriberFailure.compareAndSet(null, failure));
        subscriber.start();
        splitAssigned = true;
    }

    @Override
    public void handleNoMoreSplits() {
        // The single subscription split remains active for the lifetime of the streaming job.

View on GitHub (pinned to cf67b549a7)