apache/beam · error · IllegalArgumentException

returnLength cannot be 0 or pattern cannot be empty.

Error message

returnLength cannot be 0 or pattern cannot be empty.

What it means

The LPAD UDF for STRING inputs validates that returnLength is at least -1 and that the pattern is non-empty; otherwise it throws IllegalArgumentException. (The check returnLength < -1 corresponds to the documented contract; null returnLength would NPE earlier.)

Source

Thrown at sdks/java/extensions/sql/src/main/java/org/apache/beam/sdk/extensions/sql/impl/udf/BuiltinStringFunctions.java:129

  }

  @UDF(
      funcName = "LPAD",
      parameterArray = {TypeName.STRING, TypeName.INT64},
      returnType = TypeName.STRING)
  @Strict
  public String lpad(String originalValue, Long returnLength) {
    return lpad(originalValue, returnLength, " ");
  }

  @UDF(
      funcName = "LPAD",
      parameterArray = {TypeName.STRING, TypeName.INT64, TypeName.STRING},
      returnType = TypeName.STRING)
  @Strict
  public String lpad(String originalValue, Long returnLength, String pattern) {
    if (returnLength < -1 || pattern.isEmpty()) {
      throw new IllegalArgumentException("returnLength cannot be 0 or pattern cannot be empty.");
    }

    if (originalValue.length() == returnLength) {
      return originalValue;
    } else if (originalValue.length() < returnLength) { // add padding to left
      return StringUtils.leftPad(originalValue, Math.toIntExact(returnLength), pattern);
    } else { // truncating string by str.substring
      // Java String can only hold a string with Integer.MAX_VALUE as longest length.
      return originalValue.substring(0, Math.toIntExact(returnLength));
    }
  }

  @UDF(
      funcName = "LPAD",
      parameterArray = {TypeName.BYTES, TypeName.INT64},
      returnType = TypeName.BYTES)
  @Strict
  public byte[] lpad(byte[] originalValue, Long returnLength) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Provide a non-empty pattern string to LPAD
2. Ensure returnLength is >= -1 (typically >= 0)
3. Coalesce NULL/empty pattern inputs to a default pad character (e.g. ' ')
4. Validate parameters in application code before issuing the SQL

Example fix

// before
SELECT LPAD(name, 10, '') FROM users;
// after
SELECT LPAD(name, 10, ' ') FROM users;

static boolean isValidLpadParams(String value, Long returnLength, String pattern) {
  return returnLength != null && returnLength >= -1
      && pattern != null && !pattern.isEmpty()
      && value != null;
}

static boolean canLpad(Long returnLength, String pattern) {
  return returnLength != null && returnLength >= -1 && pattern != null && !pattern.isEmpty();
}

try {
  return udf.lpad(value, len, pattern);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("returnLength") || e.getMessage().contains("pattern")) {
    return udf.lpad(value, len, DEFAULT_PAD);
  }
  throw e;
}

When it happens

Trigger: Calling LPAD(value, 0, 'x') is allowed by this check but LPAD with pattern '' (empty string) throws; also any returnLength below -1. Note the message text is misleading — it is raised for empty pattern or returnLength < -1, not for 0.

Common situations: Dynamic SQL building where the pattern parameter is computed and comes back empty; passing negative lengths from user input; porting queries from other engines with different padding semantics.

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

• Failed to load user-provided jar(s).
• CalcFn failed to evaluate: ${processElementBlock}
• offset is negative:
• offset exceeds the buffer limit. offset: , limit:
• length is negative:

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/ec89eebc0a3c886e. Report an issue: GitHub.