t8y2/dbx · error · SQLException

The manual transaction belongs to a different JDBC connectio

Error message

The manual transaction belongs to a different JDBC connection

What it means

When a manual transaction is active, activeManualTransactionConnection additionally checks that the connection config passed by the caller matches the connection the transaction was opened on, comparing connectionKey(connection) with sharedConnectionKey. A mismatch means the caller is trying to commit/extend a transaction that belongs to a different database connection.

Source

Thrown at plugins/jdbc/src/main/java/app/dbx/jdbc/DbxJdbcPlugin.java:1093

        conn.setAutoCommit(true);
        manualTransactionActive = false;
        return okResult();
    }

    private static ObjectNode rollbackManualTransaction() throws SQLException {
        Connection conn = activeManualTransactionConnection(null);
        conn.rollback();
        conn.setAutoCommit(true);
        manualTransactionActive = false;
        return okResult();
    }

    private static Connection activeManualTransactionConnection(JsonNode connection) throws SQLException {
        if (!manualTransactionActive || sharedConnection == null || sharedConnection.isClosed()) {
            throw new SQLException("No manual transaction is active");
        }
        if (connection != null && !connectionKey(connection).equals(sharedConnectionKey)) {
            throw new SQLException("The manual transaction belongs to a different JDBC connection");
        }
        return sharedConnection;
    }

    private static ObjectNode okResult() {
        ObjectNode result = MAPPER.createObjectNode();
        result.put("ok", true);
        return result;
    }

    private record ExecutedStatement(ResultSet resultSet, int updateCount) {
    }

    private static final class QuerySession {
        private final String id;
        private final Statement statement;
        private final ResultSet resultSet;
        private final ResultSetMetaData meta;

View on GitHub (pinned to c0390bff16)

Solutions

Pass the exact same connection config object/values used at begin time for all subsequent transaction operations.
Track which connection config started the transaction in your script and use it consistently until commit/rollback.
Check for stray differences in the config (extra/missing properties change the connectionKey) — normalize the config source.
If you genuinely need a different connection, commit or roll back the current transaction first, then begin a new one on the other connection.

Example fix

// before
beginTx(connA);                 // jdbc:db://host/app
execWithinTx(connB, stmt);      // different key -> error
// after
beginTx(connA);
execWithinTx(connA, stmt);      // same connection
commitTx(connA);

Defensive patterns

Strategy: validation

Validate before calling

// Java: pin one connection config for the whole transaction
final java.util.Map<String,Object> txConn = java.util.Map.copyOf(connCfg); // immutable snapshot
plugin.beginManualTransaction(txConn);
// every later call MUST pass txConn:
plugin.execute(txConn, sql);
plugin.commitManualTransaction(txConn);

Try / catch

try {
    plugin.commitManualTransaction(connCfg);
} catch (java.sql.SQLException e) {
    if (e.getMessage().contains("different JDBC connection")) {
        throw new IllegalStateException("commit called with wrong connection config; use the one passed to begin", e);
    }
    throw e;
}

Prevention

Capture the begin-time connection config and reuse the identical object until commit/rollback
Avoid mutating connection config (adding properties) mid-transaction — it changes the connectionKey
Commit before switching to another connection in loops
Centralize transaction handling in one helper that takes and reuses a single config

When it happens

Trigger: Beginning a manual transaction on connection A, then calling commit/rollback or executing a transactional statement while passing connection B's config (different url/credentials yielding a different connectionKey).

Common situations: Copy-pasted connection configs where host/db/credentials differ slightly (producing a different key), scripts iterating over multiple connections and reusing one transaction handle, or editing connection details mid-transaction.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/3800d6b0300b95f0. Report an issue: GitHub.