apache/druid · error · IllegalArgumentException

Value [%s] is not valid for property [%s], expected %s

Error message

Value [%s] is not valid for property [%s], expected %s

What it means

ModelProperties.decode converts a raw property value into the declared Java type using Jackson's convertValue. When the conversion fails — the value's shape or type does not match the property's declared type — this IAE is thrown with the property name and expected type name.

Source

Thrown at server/src/main/java/org/apache/druid/catalog/model/ModelProperties.java:143

    }

    /**
     * Convert the value from the deserialized JSON format to the type
     * required by this field data type. Also used to decode values from
     * SQL parameters. As a side effect, verifies that the value is of
     * the correct type.
     */
    @Override
    public T decode(Object value, ObjectMapper jsonMapper)
    {
      if (value == null) {
        return null;
      }
      try {
        return jsonMapper.convertValue(value, valueClass);
      }
      catch (Exception e) {
        throw new IAE(
            "Value [%s] is not valid for property [%s], expected %s",
            value,
            name,
            typeName()
        );
      }
    }

    /**
     * Validate that the given value is valid for this property.
     * By default, does a value conversion and discards the value.
     */
    @Override
    public void validate(Object value, ObjectMapper jsonMapper)
    {
      decode(value, jsonMapper);
    }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Match the value to the expected type named in the message (typeName() output), e.g. supply a JSON object instead of a string.
2. Remove surrounding quotes from numeric/boolean values in the config.
3. Check the model definition (ModelProperties) to confirm the declared type, and if the model is wrong, correct the property's declared type.

Example fix

// before
{"properties": {"replicas": "3"}}
// after
{"properties": {"replicas": 3}}

// ensure value's JSON type matches the declared property type before submit
Object v = props.get(name);
if (expectedType == Integer.class && !(v instanceof Number)) {
  throw new IllegalArgumentException(name + " must be an integer");
}

boolean matchesExpectedType(Object v, Class<?> expected) {
  return v == null || expected.isInstance(v)
      || (expected == Integer.class && v instanceof Number);
}

try { Object decoded = propDef.decode(mapper, rawValue); } catch (IllegalArgumentException e) { log.error("Property type error: %s", e.getMessage()); }

When it happens

Trigger: Supplying a property value whose type mismatches the model definition: e.g. a string where an integer/map/list is declared, an object where a scalar is expected. jsonMapper.convertValue throws and decode wraps it as IAE.

Common situations: JSON/YAML config where a property is written as a string ("replicas": "3") while the model declares an integer; nested map properties given as flat strings; type drift after a model definition change or upgrade.

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

• Value [%s] is not valid for property [%s], expected type [%s
• [%s] column must have type [%s] or no type. Found [%s]
• Value [%s] is not valid for property [%s]
• Value of field %s must be a list, found %s
• Expected a number or an instance of DDSketch, but received [

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/4428442eddeda57b. Report an issue: GitHub.