apache/iceberg · error · UnsupportedOperationException

Cannot drop branch on non-Iceberg table: $table

Error message

Cannot drop branch on non-Iceberg table: $table

What it means

This UnsupportedOperationException is thrown by Spark's DROP BRANCH execution when the resolved table is not an Iceberg table. Removing snapshot references (branches) is only supported on Iceberg tables; the non-Iceberg case falls to the default match and throws. Note the related NoSuchNamespaceException/NoSuchRefException path handles missing branches on Iceberg tables separately.

Source

Thrown at spark/v4.2/spark-extensions/src/main/scala/org/apache/spark/sql/execution/datasources/v2/DropBranchExec.scala:47

    ident: Identifier,
    branch: String,
    ifExists: Boolean)
    extends LeafV2CommandExec {

  import org.apache.spark.sql.connector.catalog.CatalogV2Implicits._

  override lazy val output: Seq[Attribute] = Nil

  override protected def run(): Seq[InternalRow] = {
    catalog.loadTable(ident) match {
      case iceberg: SparkTable =>
        val ref = iceberg.table().refs().get(branch)
        if (ref != null || !ifExists) {
          iceberg.table().manageSnapshots().removeBranch(branch).commit()
        }

      case table =>
        throw new UnsupportedOperationException(s"Cannot drop branch on non-Iceberg table: $table")
    }

    Nil
  }

  override def simpleString(maxFields: Int): String = {
    s"DropBranch branch: ${branch} for table: ${ident.quoted}"
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Ensure the table is an Iceberg table before issuing DROP BRANCH
2. Qualify with the Iceberg catalog: ALTER TABLE iceberg_catalog.db.tbl DROP BRANCH b1
3. Check catalog registration in Spark conf
4. Add IF EXISTS only guards missing branches; it does not make non-Iceberg tables supported

Example fix

// before (generic catalog)
ALTER TABLE my_table DROP BRANCH audit;
// after
ALTER TABLE iceberg_catalog.db.my_table DROP BRANCH audit;

val icebergTable = Spark3Util.loadIcebergTable(spark, fullTableName)
require(icebergTable != null, s"$fullTableName is not an Iceberg table")

def isIcebergTable(spark: SparkSession, name: String): Boolean =
  scala.util.Try(Spark3Util.loadIcebergTable(spark, name)).map(_ != null).getOrElse(false)

When it happens

Trigger: Running 'ALTER TABLE ... DROP BRANCH ...' where the table resolves to a non-Iceberg Spark table, e.g. through a Delta or Hive catalog.

Common situations: Table created in a non-Iceberg format but referenced without catalog qualification; catalog alias misconfiguration; copy-paste of Iceberg DDL onto another provider's table.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Cannot create or replace branch on non-Iceberg table: $table
• Renaming a view is not supported by catalog: ${catalogName}
• Cannot convert predicate to SQL: <pred>
• Cannot convert term to SQL: <term>
• Cannot retrieve UUID for table <table.name()>

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