apache/shardingsphere · error · InvalidTransactionHandleException

Invalid transaction handle: %d

Error message

Invalid transaction handle: %d

What it means

Error "Invalid transaction handle: %d" thrown in apache/shardingsphere.

Source

Thrown at proxy/frontend/dialect/firebird/src/main/java/org/apache/shardingsphere/proxy/frontend/firebird/command/query/transaction/FirebirdRollbackTransactionCommandExecutor.java:57

    private final FirebirdRollbackTransactionPacket packet;
    
    private final ConnectionSession connectionSession;
    
    @Override
    public Collection<DatabasePacket> execute() throws SQLException {
        int transactionHandle = packet.getTransactionId();
        validateTransactionHandle(transactionHandle);
        if (!connectionSession.isAutoCommit()) {
            ProxyBackendTransactionManager transactionManager = new ProxyBackendTransactionManager(connectionSession.getDatabaseConnectionManager());
            transactionManager.rollback();
        }
        FirebirdTransactionIdGenerator.getInstance().closeTransaction(connectionSession.getConnectionId(), transactionHandle);
        return Collections.singleton(new FirebirdGenericResponsePacket());
    }
    
    private void validateTransactionHandle(final int transactionHandle) {
        if (!FirebirdTransactionIdGenerator.getInstance().isTransactionActive(connectionSession.getConnectionId(), transactionHandle)) {
            throw new InvalidTransactionHandleException(transactionHandle);
        }
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Use the transaction handle returned by the original start-transaction request.
2. Ensure the transaction is still open; a committed or rolled-back handle is invalid.
3. Check that the handle was not corrupted or truncated on the wire.

When it happens

Trigger: A Firebird op_rollback arrives with a transaction handle the proxy does not recognize.

Common situations: Client bugs, reconnects, or duplicated rollback packets referencing an already-closed transaction handle.

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/e30dd7e840ced39c. Report an issue: GitHub.