apache/iceberg · error · IllegalArgumentException

Invalid bit width for int

Error message

Invalid bit width for int: ${bitWidth}

What it means

Thrown by VariantReaderBuilder's IntLogicalTypeAnnotation visitor when the signed INT logical annotation has a bit width other than 8, 16, 32, or 64. Valid Variant integer shredding widths are only those four; anything else is an invalid schema configuration.

Solutions

1. Inspect the typed_value column schema and correct its INT logical annotation bit width to 8, 16, 32, or 64.
2. Rewrite the file with a standard writer so the logical type is normalized to a legal bit width.
3. Disable shredding for this Variant column so no typed integer column is read.

Example fix

// before
.as(LogicalTypeAnnotation.intType(12, true))

// after
.as(LogicalTypeAnnotation.intType(16, true))

int w = logical.getBitWidth();
Preconditions.checkArgument(w == 8 || w == 16 || w == 32 || w == 64,
    "INT bit width must be 8/16/32/64, got %s", w);

boolean hasLegalIntWidth(LogicalTypeAnnotation l) {
  return l instanceof IntLogicalTypeAnnotation i
      && Set.of(8, 16, 32, 64).contains(i.getBitWidth());
}

try {
  buildReader(typedValueSchema);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Invalid bit width")) normalizeSchemaAndRebuild();
  else throw e;
}

When it happens

Trigger: visit(IntLogicalTypeAnnotation) with a signed type whose getBitWidth() returns a value outside {8,16,32,64} (e.g. a malformed or hand-crafted logical annotation).

Common situations: Corrupt or hand-edited Parquet schemas; custom logical type annotations with unusual bit widths; a buggy third-party writer generating nonstandard INT logical types.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Invalid bit width for int
• Invalid primitive type for decimal
• Invalid primitive type for decimal
• Unknown primitive physical type
• Unsupported shredded value type

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

Appendix: source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/VariantReaderBuilder.java:261

                  PhysicalType.INT64, ParquetValueReaders.unboxed(desc));
          break;
        case 32:
          reader =
              ParquetVariantReaders.asVariant(
                  PhysicalType.INT32, ParquetValueReaders.unboxed(desc));
          break;
        case 16:
          reader =
              ParquetVariantReaders.asVariant(
                  PhysicalType.INT16, ParquetValueReaders.intsAsShort(desc));
          break;
        case 8:
          reader =
              ParquetVariantReaders.asVariant(
                  PhysicalType.INT8, ParquetValueReaders.intsAsByte(desc));
          break;
        default:
          throw new IllegalArgumentException("Invalid bit width for int: " + logical.getBitWidth());
      }

      return Optional.of(reader);
    }

    @Override
    public Optional<VariantValueReader> visit(UUIDLogicalTypeAnnotation logical) {
      VariantValueReader reader =
          ParquetVariantReaders.asVariant(PhysicalType.UUID, ParquetValueReaders.uuids(desc));
      return Optional.of(reader);
    }

    private static PhysicalType variantDecimalType(PrimitiveType primitive) {
      switch (primitive.getPrimitiveTypeName()) {
        case FIXED_LEN_BYTE_ARRAY:
        case BINARY:
          return PhysicalType.DECIMAL16;
        case INT64:

View on GitHub (pinned to 86d9c8fc54)