apache/iceberg · error · IllegalArgumentException

String.format("Invalid snapshot ref type: %s", snapshotRefTy

Error message

String.format("Invalid snapshot ref type: %s", snapshotRefType)

What it means

SnapshotRefType.fromString(String) parses a branch/tag reference type string into the SnapshotRefType enum (BRANCH or TAG). Null input is rejected up front, and any non-null value that is not a valid enum name (case-insensitive) is rethrown as this IllegalArgumentException wrapping the original error.

Source

Thrown at api/src/main/java/org/apache/iceberg/SnapshotRefType.java:33

 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.iceberg;

import java.util.Locale;
import org.apache.iceberg.relocated.com.google.common.base.Preconditions;

public enum SnapshotRefType {
  BRANCH,
  TAG;

  public static SnapshotRefType fromString(String snapshotRefType) {
    Preconditions.checkArgument(null != snapshotRefType, "Invalid snapshot ref type: null");
    try {
      return SnapshotRefType.valueOf(snapshotRefType.toUpperCase(Locale.ROOT));
    } catch (IllegalArgumentException e) {
      throw new IllegalArgumentException(
          String.format("Invalid snapshot ref type: %s", snapshotRefType), e);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

Use exactly "branch" or "tag" (case-insensitive) as the ref type string.
Trim whitespace and check for typos before calling fromString.
Guard with SnapshotRefType.valueOf-style validation or catch IllegalArgumentException and default to BRANCH when the type is absent.

Example fix

// before
SnapshotRefType type = SnapshotRefType.fromString("branches"); // invalid
// after
SnapshotRefType type = SnapshotRefType.fromString("branch");

Defensive patterns

Strategy: validation

Validate before calling

static boolean isValidRefType(String s) {
  return "branch".equalsIgnoreCase(s) || "tag".equalsIgnoreCase(s);
}

Try / catch

try {
  type = SnapshotRefType.fromString(refType);
} catch (IllegalArgumentException e) {
  type = SnapshotRefType.BRANCH; // default with logged warning
}

Prevention

Normalize ref type strings (trim + lowercase) before parsing.
Only accept "branch" or "tag" at configuration boundaries.
When splitting names like "main@tag", validate the type suffix before calling fromString.

When it happens

Trigger: Passing values like "branches", "tag ", "snapshot", or a misspelled "brnch" to fromString — typically when parsing snapshot ref names containing an @ delimiter (e.g. "main@tag") or REST/catalog ref metadata.

Common situations: Typo in SQL like ALTER TABLE ... CREATE TAG/BRANCH handling, REST catalog ref payloads with unexpected type strings, or configuration of ref names where the type suffix was hand-written.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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