What causes "Cannot parse default as a %s value: %s" in apache/iceberg?

Fix the schema JSON so the decimal default is a quoted string matching the declared scale, e.g. "default": "12.3" for DecimalType.of(4, 1).

apache/iceberg · error · IllegalArgumentException

Cannot parse default as a %s value: %s

Error message

Cannot parse default as a %s value: %s

What it means

SingleValueParser.fromJson parses a JSON default value for a column type when reading schema JSON. For DecimalType the JSON node must be a textual decimal string, and the parsed value's scale must exactly equal the type's declared scale. This error is thrown when the default value is not a text node or cannot be parsed as a BigDecimal (or, in the adjacent check, has a mismatched scale), i.e. the schema JSON does not conform to the Iceberg spec for decimal defaults.

Source

Thrown at core/src/main/java/org/apache/iceberg/SingleValueParser.java:94

            "Cannot parse default as a %s value: %s",
            type,
            defaultValue);
        return defaultValue.floatValue();
      case DOUBLE:
        Preconditions.checkArgument(
            defaultValue.isFloatingPointNumber(),
            "Cannot parse default as a %s value: %s",
            type,
            defaultValue);
        return defaultValue.doubleValue();
      case DECIMAL:
        Preconditions.checkArgument(
            defaultValue.isTextual(), "Cannot parse default as a %s value: %s", type, defaultValue);
        BigDecimal retDecimal;
        try {
          retDecimal = new BigDecimal(defaultValue.textValue());
        } catch (NumberFormatException e) {
          throw new IllegalArgumentException(
              String.format("Cannot parse default as a %s value: %s", type, defaultValue), e);
        }
        Preconditions.checkArgument(
            retDecimal.scale() == ((Types.DecimalType) type).scale(),
            "Cannot parse default as a %s value: %s, the scale doesn't match",
            type,
            defaultValue);
        return retDecimal;
      case STRING:
        Preconditions.checkArgument(
            defaultValue.isTextual(), "Cannot parse default as a %s value: %s", type, defaultValue);
        return defaultValue.textValue();
      case UUID:
        Preconditions.checkArgument(
            defaultValue.isTextual() && defaultValue.textValue().length() == 36,
            "Cannot parse default as a %s value: %s",
            type,
            defaultValue);

View on GitHub (pinned to 86d9c8fc54)

Solutions

Fix the schema JSON so the decimal default is a quoted string matching the declared scale, e.g. "default": "12.3" for DecimalType.of(4, 1).
Remove the invalid default value from the schema JSON and add it programmatically via UpdateSchema (setDefault) so Iceberg validates and formats it correctly.
Validate the JSON before parsing: check defaultValue.isTextual() and new BigDecimal(text).scale() == expectedScale, and normalize (setScale/stripTrailingZeros) as needed.

Example fix

// before (schema JSON)
{"type": "decimal(4, 1)", "default": 12.3}

// after
{"type": "decimal(4, 1)", "default": "12.3"}

Defensive patterns

Strategy: validation

Validate before calling

if (node == null || !node.isTextual()) {
  throw new IllegalArgumentException("Decimal default must be a JSON string");
}
java.math.BigDecimal d = new java.math.BigDecimal(node.textValue());
if (d.scale() != decimalType.scale()) {
  throw new IllegalArgumentException("Decimal default scale " + d.scale() + " != " + decimalType.scale());
}

Type guard

null

Try / catch

try {
  Object v = SingleValueParser.fromJson(node, Types.DecimalType.of(precision, scale));
} catch (IllegalArgumentException | NumberFormatException e) {
  throw new IllegalArgumentException("Invalid decimal default '" + node.textValue()
      + "' for decimal(" + precision + "," + scale + ")", e);
}

Prevention

Always emit decimal default values as quoted JSON strings, never JSON numbers.
Ensure the literal's fractional digits exactly match the declared scale ("12.30" for scale 2).
Set defaults through UpdateSchema.setDefault so Iceberg validates and serializes them correctly.
Pre-validate hand-written or third-party schema JSON with SchemaParser before use.

When it happens

Trigger: Calling SingleValueParser.fromJson(jsonNode, Types.DecimalType.of(precision, scale)) with a JSON node that is non-textual (numeric/boolean/object), contains a non-decimal string (e.g. "1.2.3", "abc", "1e999" overflowing), or a decimal string whose scale differs from the type's scale (e.g. "1.50" for scale(1)).

Common situations: Hand-written or third-party-generated schema JSON where decimal defaults were written as JSON numbers instead of strings, or with the wrong number of fractional digits; schema files produced by other tools that don't follow Iceberg's kebab-case JSON conventions; typos in default values in table metadata.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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