apache/iceberg · error · IllegalArgumentException

Unsupported width for transform

Error message

Unsupported width for transform: %s

What it means

findWidth extracts the integer width parameter from a Spark truncate(W) transform literal. The literal must be a positive Integer (or Long below Integer.MAX_VALUE); otherwise Preconditions.checkArgument fails with 'Unsupported width for transform'.

Solutions

1. Use a positive integer width for truncate that fits in an int (>0 and < 2147483648)
2. Fix the width literal in the PARTITIONED BY clause, e.g. truncate(10, col)
3. If the value comes from code/config, validate width > 0 and width < Integer.MAX_VALUE before building the transform

Example fix

// before
PARTITIONED BY truncate(0, id)
// after
PARTITIONED BY truncate(10, id)

long width = /* width value */;
if (width <= 0 || width >= Integer.MAX_VALUE) {
  throw new IllegalArgumentException("truncate width must be > 0 and < Integer.MAX_VALUE: " + width);
}

boolean isValidWidth(Object v) {
  long w = (v instanceof Number n) ? n.longValue() : Long.MIN_VALUE;
  return w > 0 && w < Integer.MAX_VALUE;
}

try {
  builder.truncate(colName, width);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("Invalid truncate width in partition clause: " + e.getMessage(), e);
}

When it happens

Trigger: CREATE TABLE ... PARTITIONED BY truncate(0, col) or truncate(-5, col); truncate(3000000000, col) where the Long literal exceeds Integer.MAX_VALUE; passing a non-integer literal that findWidth tries to coerce.

Common situations: Typos in DDL partition clause, programmatically generated transforms with invalid width, copy-pasted widths from systems allowing 0 or huge widths.

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

• Cannot find width for transform:
• Cannot find width for transform
• Cannot find width for transform
• Cannot find width for transform: <transform.describe()>
• Already closed files for partition:

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

Appendix: source

Thrown at spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:487

      }
    }

    return builder.build();
  }

  @SuppressWarnings("unchecked")
  private static int findWidth(Transform transform) {
    for (Expression expr : transform.arguments()) {
      if (expr instanceof Literal) {
        if (((Literal) expr).dataType() instanceof IntegerType) {
          Literal<Integer> lit = (Literal<Integer>) expr;
          Preconditions.checkArgument(
              lit.value() > 0, "Unsupported width for transform: %s", transform.describe());
          return lit.value();

        } else if (((Literal) expr).dataType() instanceof LongType) {
          Literal<Long> lit = (Literal<Long>) expr;
          Preconditions.checkArgument(
              lit.value() > 0 && lit.value() < Integer.MAX_VALUE,
              "Unsupported width for transform: %s",
              transform.describe());
          if (lit.value() > Integer.MAX_VALUE) {
            throw new IllegalArgumentException();
          }
          return lit.value().intValue();
        }
      }
    }

    throw new IllegalArgumentException("Cannot find width for transform: " + transform.describe());
  }

  private static String leafName(String[] fieldNames) {
    Preconditions.checkArgument(
        fieldNames.length > 0, "Invalid field name: at least one name is required");
    return fieldNames[fieldNames.length - 1];

View on GitHub (pinned to 86d9c8fc54)