What causes "Type ConnectorCommitHandle is expected" in prestodb/presto?

Ensure all nodes in the cluster run the same Presto version (complete rolling upgrade)

prestodb/presto · error · PrestoException

INVALID_ARGUMENTS

INVALID_ARGUMENTS

Error message

Type ConnectorCommitHandle is expected

What it means

Thrown by QueryStateMachine.attachSerializedCommitOutput when deserializing query commit output: an element of the commitHandles list is not an instance of ConnectorCommitHandle. This indicates corrupted or incompatible serialized state being re-attached to inputs during query completion.

Source

Thrown at presto-main-base/src/main/java/com/facebook/presto/execution/QueryStateMachine.java:647

    }

    private void addSerializedCommitOutputToInputs(List<?> commitHandles)
    {
        ImmutableSet.Builder<Input> builder = ImmutableSet.builder();

        for (Input input : inputs.get()) {
            builder.add(attachSerializedCommitOutput(input, commitHandles));
        }

        inputs.set(builder.build());
    }

    private Input attachSerializedCommitOutput(Input input, List<?> commitHandles)
    {
        SchemaTableName table = new SchemaTableName(input.getSchema(), input.getTable());
        for (Object handle : commitHandles) {
            if (!(handle instanceof ConnectorCommitHandle)) {
                throw new PrestoException(INVALID_ARGUMENTS, "Type ConnectorCommitHandle is expected");
            }

            ConnectorCommitHandle commitHandle = (ConnectorCommitHandle) handle;
            if (commitHandle.hasCommitOutput(table)) {
                return new Input(
                        input.getConnectorId(),
                        input.getSchema(),
                        input.getTable(),
                        input.getConnectorInfo(),
                        input.getColumns(),
                        input.getStatistics(),
                        Optional.of(commitHandle.getCommitOutputForRead(table)));
            }
        }
        return input;
    }

    public Map<String, String> getSetSessionProperties()

View on GitHub (pinned to 55bb57d202)

Solutions

Ensure all nodes in the cluster run the same Presto version (complete rolling upgrade)
Discard and re-run the affected query instead of replaying its commit state
If a custom connector is involved, verify it returns ConnectorCommitHandle instances from its commit method

Defensive patterns

Strategy: type-guard

Validate before calling

if (handles.stream().allMatch(h -> h instanceof ConnectorCommitHandle)) {
    stateMachine.attachSerializedCommitOutput(input, handles);
}

Type guard

boolean isCommitHandle(Object o) { return o instanceof ConnectorCommitHandle; }

Try / catch

try { attachSerializedCommitOutput(input, handles); } catch (PrestoException e) { if (e.getErrorCode().getCode() == StandardErrorCode.INVALID_ARGUMENTS.toErrorCodeCode()) { /* drop corrupted state; re-run query */ } throw e; }

Prevention

Keep the cluster on a single Presto version, especially across rolling upgrades
Never hand-edit or partially restore serialized query/session state
In custom connectors, always return ConnectorCommitHandle from commit APIs

When it happens

Trigger: Replaying/attaching serialized commit output where a list element fails `handle instanceof ConnectorCommitHandle` — typically deserialized objects from a session/commit payload produced by an incompatible version or a malformed payload.

Common situations: Cluster rolling upgrade with mixed Presto versions exchanging serialized commit handles; manually replayed or restored coordinator state; custom connector returning a wrong object type in commit output.

Related errors

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/2916cdb663408c99. Report an issue: GitHub.