t8y2/dbx · error · UnsupportedOperationException

Transactions are not supported by this JDBC driver

Error message

Transactions are not supported by this JDBC driver

What it means

TransactionExecutor.executeStatements() checks whether the JDBC connection supports transactions (DatabaseMetaData.supportsTransactions) before starting one. If the driver reports transactions as unsupported, it throws UnsupportedOperationException instead of silently running the statements in auto-commit mode. This is deliberate: callers depend on the explicit transaction to get all-or-nothing writes, so degrading would risk partial writes.

Source

Thrown at agents/common/src/main/java/com/dbx/agent/TransactionExecutor.java:61

        StatementRunner runner
    ) {
        return executeStatements(conn, statements, schema, setSchemaSql, () -> "", runner);
    }

    public static QueryResult executeStatements(
        Connection conn,
        List<String> statements,
        String schema,
        Function<String, String> setSchemaSql,
        Supplier<String> resetSchemaSql,
        StatementRunner runner
    ) {
        return unchecked(() -> {
            long start = System.currentTimeMillis();
            if (!supportsTransactions(conn)) {
                // An explicit transaction request must not degrade to auto-commit:
                // callers rely on it to avoid partial writes when a later statement fails.
                throw new UnsupportedOperationException("Transactions are not supported by this JDBC driver");
            }

            boolean savedAutoCommit = conn.getAutoCommit();
            conn.setAutoCommit(false);
            try {
                long totalAffected = executeAll(conn, statements, schema, setSchemaSql, resetSchemaSql, runner);
                conn.commit();
                return result(totalAffected, start);
            } catch (Exception e) {
                conn.rollback();
                throw e;
            } finally {
                conn.setAutoCommit(savedAutoCommit);
            }
        });
    }

    private static long executeAll(

View on GitHub (pinned to c0390bff16)

Solutions

Use a JDBC driver/database that supports transactions (the driver currently in use reports supportsTransactions()==false).
Verify the driver class/URL in the datasource config — a wrong fallback driver may have been selected (e.g. a generic bridge instead of the real vendor driver).
If writes do not need atomicity, use a non-transactional execution path (execute statements individually in auto-commit) instead of the transaction executor.
Catch UnsupportedOperationException and surface a clear configuration error to the user rather than retrying.

Example fix

// before
TransactionExecutor.executeStatements(conn, statements, schema, setSchemaSql, resetSchemaSql, runner); // throws on non-transactional driver
// after
if (!conn.getMetaData().supportsTransactions()) {
    throw new IllegalStateException(
        "Datasource driver " + conn.getMetaData().getDriverName() + " does not support transactions; " +
        "configure a transaction-capable driver for multi-statement writes");
}
TransactionExecutor.executeStatements(conn, statements, schema, setSchemaSql, resetSchemaSql, runner);

Defensive patterns

Strategy: validation

Validate before calling

if (!conn.getMetaData().supportsTransactions()) {
    throw new IllegalStateException("Driver " + conn.getMetaData().getDriverName() + " cannot run transactional multi-statement writes");
}

Type guard

static boolean supportsTransactions(Connection conn) throws SQLException {
    return conn.getMetaData().supportsTransactions();
}

Try / catch

try {
    TransactionExecutor.executeStatements(conn, statements, schema, setSchemaSql, resetSchemaSql, runner);
} catch (UnsupportedOperationException e) {
    throw new SQLException("Transactional execution unavailable: " + e.getMessage() +
        ". Configure a transaction-capable JDBC driver.", e);
}

Prevention

Verify DatabaseMetaData.supportsTransactions() when configuring a datasource
Avoid generic/bridge JDBC drivers for write workloads; use the vendor driver
Do not mix auto-commit assumptions with transactional execution paths
Fail fast at connection setup if transaction support is required by your app

When it happens

Trigger: Calling executeStatements/executeUpdateStatements with a Connection whose driver reports supportsTransactions()==false — e.g. a connection over a driver/wrapper that does not implement transactions (some streaming bridges, certain read-only or no-transaction datasources, custom driver wrappers).

Common situations: Pointing the agent at a non-transactional JDBC driver or a wrapper (pooling/proxy driver, CSV/file-based driver) that reports no transaction support; misconfigured datasource where the wrong driver class is loaded; embedded or test drivers that skip transaction support.

Related errors

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