apache/iceberg · error · ValidationException

Table property %s must have integer value

Error message

Table property %s must have integer value

What it means

PropertyUtil.validateCommitProperties checks that each expected commit-related table property, when present, parses as an integer and is non-negative. A non-numeric value throws ValidationException naming the offending property key.

Source

Thrown at core/src/main/java/org/apache/iceberg/util/PropertyUtil.java:142

    if (value != null) {
      return value;
    }
    return defaultValue;
  }

  /**
   * Validate the table commit related properties to have non-negative integer on table creation to
   * prevent commit failure
   */
  public static void validateCommitProperties(Map<String, String> properties) {
    for (String commitProperty : COMMIT_PROPERTIES) {
      String value = properties.get(commitProperty);
      if (value != null) {
        int parsedValue;
        try {
          parsedValue = Integer.parseInt(value);
        } catch (NumberFormatException e) {
          throw new ValidationException(
              "Table property %s must have integer value", commitProperty);
        }
        ValidationException.check(
            parsedValue >= 0,
            "Table property %s must have non negative integer value",
            commitProperty);
      }
    }
  }

  /**
   * Returns subset of provided map with keys matching the provided prefix. Matching is
   * case-sensitive and the matching prefix is removed from the keys in returned map.
   *
   * @param properties input map
   * @param prefix prefix to choose keys from input map
   * @return subset of input map with keys starting with provided prefix and prefix trimmed out
   */

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Correct the property value to a non-negative integer string (e.g. '4')
2. Remove the property to fall back to the default
3. Check the property name — some properties accept long/double, not int

Example fix

// before
table.updateProperties().set("commit.retry.num-retries", "three").commit();
// after
table.updateProperties().set("commit.retry.num-retries", "4").commit();

String v = properties.get("commit.retry.num-retries");
if (v != null) {
  try { Integer.parseInt(v); } catch (NumberFormatException e) { throw new IllegalArgumentException("property must be integer, got: " + v); }
}

try { table.refresh(); } catch (ValidationException e) { /* fix property value then retry commit */ }

When it happens

Trigger: Setting a table property like commit.retry.num-retries or similar numeric property to a non-integer string (e.g. "three", "1.5", "") before a commit.

Common situations: Hand-edited table properties, Terraform/SQL SET TBLPROPERTIES with wrong type, copy-paste from docs with wrong unit.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Cannot specify both %s and %s
• Invalid distribution mode: %s
• Invalid rewrite job order name: %s
• Unsorted order ID must be 0
• Sort order ID 0 is reserved for unsorted order

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