apache/iceberg · error · java.lang.IllegalArgumentException

Cannot find width for transform: %s

Error message

Cannot find width for transform: %s

What it means

findWidth extracts the width/parameter of a Spark truncate transform from its first literal argument. If the transform has no Long literal argument, the method exhausts its search and throws this IllegalArgumentException naming the transform description.

Source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:495

          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];
  }

  private static String peerName(String[] fieldNames, String fieldName) {
    if (fieldNames.length > 1) {
      String[] peerNames = Arrays.copyOf(fieldNames, fieldNames.length);
      peerNames[fieldNames.length - 1] = fieldName;
      return DOT.join(peerNames);
    }
    return fieldName;
  }

  private static String parentName(String[] fieldNames) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Always provide truncate with a positive integer literal width, e.g. truncate(10, col)
2. Ensure the width argument is a Literal<Long>, not an expression or unresolved parameter
3. Validate the transform description before calling applySchemaChanges/applyPartitioning

Example fix

// before
Transforms.truncate(widthParam, col) // widthParam unresolved
// after
Transforms.truncate(10, col)

boolean hasLiteralWidth(Transform t) { return t.arguments().length > 0 && t.arguments()[0] instanceof Literal<?> lit && lit.value() instanceof Long; }

Long extractWidth(Transform t) { return t.arguments().length > 0 && t.arguments()[0] instanceof Literal<?> lit && lit.value() instanceof Long ? (Long) lit.value() : null; }

try { Spark3Util.toPartitionSpec(schema, parts); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Cannot find width for transform")) { /* supply truncate(N, col) with a literal width */ } else throw e; }

When it happens

Trigger: Calling truncate without a width argument or with a non-literal width (e.g. truncate(cols(x)) or truncate(NON_LITERAL_EXPR, col)) through toPartitionSpec or toIcebergTerm.

Common situations: Programmatic transform construction omitting the width; DDL where the width is supplied as a parameter/config value that resolved to null; dynamic SQL generation bugs.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Cannot find width for transform: <transform.describe()>
• Cannot truncate type: + type
• apply(value) is deprecated, use bind(Type).apply(value)
• Transform is not supported: ${transform}
• Transform is not supported:

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