apache/iceberg · error · IllegalArgumentException

Invalid bit width for int

Error message

Invalid bit width for int: ${bitWidth}

What it means

Thrown by VariantWriterBuilder's IntLogicalTypeAnnotation visitor when the signed INT logical type's bit width is not 8, 16, 32, or 64. Only those four widths have corresponding Variant writers (INT8/16/32/64 physical types); any other width is an invalid schema.

Solutions

1. Snap the typed_value integer logical type to one of 8, 16, 32, or 64 bits (signed).
2. Fix the schema-generation code to map source types onto the four legal widths (e.g. round small ints up to 8 or 16).
3. Disable shredding for the column if its type cannot be represented with a legal bit width.

Example fix

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

// after
.as(LogicalTypeAnnotation.intType(32, 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
      && (i.getBitWidth() == 8 || i.getBitWidth() == 16 || i.getBitWidth() == 32 || i.getBitWidth() == 64);
}

try {
  buildVariantWriter(schema);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Invalid bit width")) snapToLegalWidthAndRebuild();
  else throw e;
}

When it happens

Trigger: visit(IntLogicalTypeAnnotation) with logical.getBitWidth() outside {8,16,32,64} while building a shredded Variant writer.

Common situations: Hand-crafted or corrupted schemas with nonstandard INT bit widths; buggy schema-generation code computing bit widths dynamically; translating DDL with unusual integer sizes directly into Parquet 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/65bbcd2cdde6b767. Report an issue: GitHub.

Appendix: source

Thrown at parquet/src/main/java/org/apache/iceberg/parquet/VariantWriterBuilder.java:282

          writer =
              ParquetVariantWriters.primitive(
                  ParquetValueWriters.tinyints(desc), PhysicalType.INT8);
          return Optional.of(writer);
        case 16:
          writer =
              ParquetVariantWriters.primitive(ParquetValueWriters.shorts(desc), PhysicalType.INT16);
          return Optional.of(writer);
        case 32:
          writer =
              ParquetVariantWriters.primitive(ParquetValueWriters.ints(desc), PhysicalType.INT32);
          return Optional.of(writer);
        case 64:
          writer =
              ParquetVariantWriters.primitive(ParquetValueWriters.longs(desc), PhysicalType.INT64);
          return Optional.of(writer);
      }

      throw new IllegalArgumentException("Invalid bit width for int: " + logical.getBitWidth());
    }

    @Override
    public Optional<ParquetValueWriter<?>> visit(UUIDLogicalTypeAnnotation uuidLogicalType) {
      ParquetValueWriter<VariantValue> writer =
          ParquetVariantWriters.primitive(ParquetValueWriters.uuids(desc), PhysicalType.UUID);
      return Optional.of(writer);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)