apache/iceberg · error · IllegalArgumentException

Cannot find width for transform

Error message

Cannot find width for transform: ${transform.describe()}

What it means

Thrown by Spark3Util.findWidth when a truncate transform's literal width argument cannot be located. The transform's parameters did not contain a numeric literal (Literal<Integer>) from which the truncate width can be extracted.

Solutions

Pass an integer literal as the truncate width: truncate(col, 10)
Check the argument order — width is the literal parameter of the transform
Inspect transform.describe() in the message to see what was actually parsed

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

// ensure the width argument is an integer literal before calling
if (!(widthArg instanceof Literal) || !(((Literal<?>) widthArg).value() instanceof Integer)) {
  throw new IllegalArgumentException("truncate width must be an integer literal");
}

Try / catch

try {
  spec = Spark3Util.toPartitionSpec(schema, partitions);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Cannot find width for transform")) {
    // fix the truncate argument to an int literal and retry
  }
}

Prevention

Always pass truncate width as a plain integer literal
Check argument order: truncate(col, width)
Render transforms via describe() when debugging argument parsing

When it happens

Trigger: truncate(W) where W is not an integer literal — e.g. a column reference, a computed expression, a string, or a non-integer literal passed as the width.

Common situations: PARTITIONED BY (truncate(col_w, 10)) with arguments in the wrong order; using expressions like truncate(t.col, width) where width comes from a variable resolved to a non-literal; typos making the literal not match expected type.

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

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

Appendix: source

Thrown at spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/Spark3Util.java:521

          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)