apache/iceberg · error · UnsupportedOperationException

Unknown primitive physical type:

Error message

Unknown primitive physical type: 

What it means

PhysicalType.from maps a variant primitive code (Primitives.*) to its PhysicalType enum. When the byte code does not correspond to any known primitive physical type, this UnsupportedOperationException is thrown. It almost always means corrupt/unsupported variant metadata bytes or a newer spec's type code being read by an older reader.

Source

Thrown at api/src/main/java/org/apache/iceberg/variants/PhysicalType.java:113

      case Primitives.TYPE_DECIMAL8:
        return DECIMAL8;
      case Primitives.TYPE_DECIMAL16:
        return DECIMAL16;
      case Primitives.TYPE_BINARY:
        return BINARY;
      case Primitives.TYPE_STRING:
        return STRING;
      case Primitives.TYPE_TIME:
        return TIME;
      case Primitives.TYPE_TIMESTAMPTZ_NANOS:
        return TIMESTAMPTZ_NANOS;
      case Primitives.TYPE_TIMESTAMPNTZ_NANOS:
        return TIMESTAMPNTZ_NANOS;
      case Primitives.TYPE_UUID:
        return UUID;
    }

    throw new UnsupportedOperationException("Unknown primitive physical type: " + primitiveType);
  }
}

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Upgrade the Iceberg dependency so the reader recognizes newer variant primitive type codes
2. Validate variant metadata buffers before decoding (check header/type codes are in the known set)
3. Regenerate or re-write the corrupted variant data

if (primitiveType < 0 || primitiveType > Primitives.TYPE_UUID) {
  throw new IllegalStateException("unknown variant primitive code: " + primitiveType);
}

try {
  PhysicalType t = PhysicalType.from(code);
} catch (UnsupportedOperationException e) {
  // treat value as unreadable; log and skip the variant value
}

When it happens

Trigger: Calling PhysicalType.from(primitiveType) with an unknown/reserved byte code from variant metadata; reading a variant written by a newer writer that uses primitive codes this version doesn't recognize.

Common situations: Corrupted variant buffers on disk; version skew between writer and reader libraries; hand-crafted or fuzzed data reaching the variant decoder.

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

• Unsupported primitive type:
• AboveMax has no comparator
• BelowMin has no value
• BelowMin has no comparator
• Unsupported aggregate type: %s

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