apache/iceberg · error · UnsupportedOperationException

Cannot create a transaction within a transaction

Error message

Cannot create a transaction within a transaction

What it means

Iceberg does not allow nested transactions. Calling newTransaction() on the TransactionTable view inside an open transaction throws UnsupportedOperationException. Transactions must be flat: finish the outer transaction before starting another one.

Solutions

1. Reuse the existing transaction: add updates to the outer Transaction instead of opening a new one
2. Commit the outer transaction before starting a new one
3. Refactor helpers to accept a Transaction instead of a Table when called inside transactional code

Example fix

// before
Transaction tx = table.newTransaction();
Transaction inner = tx.table().newTransaction(); // throws
// after
Transaction tx = table.newTransaction();
tx.updateSchema().addColumn("c", Types.LongType.get()).commit(); // reuse outer tx
tx.commitTransaction();

function canStartTransaction(table) { return !(table instanceof BaseTransaction.TransactionTable); }

catch (UnsupportedOperationException e) { /* reuse existing transaction passed via parameter */ }

When it happens

Trigger: Calling newTransaction() where the Table handle is the one returned by an active Transaction's table() method; helper code that opens transactions on whatever Table it receives.

Common situations: Composable write utilities that each open their own transaction being combined inside a caller's transaction; framework code that wraps Table generically.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Cannot call refresh on temporary table operations
• Cannot call refresh on temporary table operations
• Cannot create transactions for a
• Managing snapshots is not supported by +…
• Operation newTransaction is not supported after the table…

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/6f8a4924d93543b0. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/BaseTransaction.java:690

    @Override
    public UpdatePartitionStatistics updatePartitionStatistics() {
      return BaseTransaction.this.updatePartitionStatistics();
    }

    @Override
    public ExpireSnapshots expireSnapshots() {
      return BaseTransaction.this.expireSnapshots();
    }

    @Override
    public ManageSnapshots manageSnapshots() {
      throw new UnsupportedOperationException(
          "Transaction tables do not support managing snapshots");
    }

    @Override
    public Transaction newTransaction() {
      throw new UnsupportedOperationException("Cannot create a transaction within a transaction");
    }

    @Override
    public FileIO io() {
      return transactionOps.io();
    }

    @Override
    public EncryptionManager encryption() {
      return transactionOps.encryption();
    }

    @Override
    public LocationProvider locationProvider() {
      return transactionOps.locationProvider();
    }

    @Override

View on GitHub (pinned to 86d9c8fc54)