What causes "Cannot set the value '{}' because the property '{}' is null." in mybatis/mybatis-3?

Initialize the collection/array field where it is declared: private List items = new ArrayList<>();

mybatis/mybatis-3 · error · ReflectionException

Cannot set the value '{}' because the property '{}' is null.

Error message

Cannot set the value '{}' because the property '{}' is null.

What it means

The set-side counterpart of the null-collection read error: BaseWrapper.setCollectionValue throws a ReflectionException when an indexed assignment like 'items[0] = value' or 'map[key] = value' targets a property whose current value is null. MyBatis does not auto-create the missing collection; the container must already exist for element assignment to proceed.

Source

Thrown at src/main/java/org/apache/ibatis/reflection/wrapper/BaseWrapper.java:82

    } else if (collection instanceof double[]) {
      return ((double[]) collection)[i];
    } else if (collection instanceof float[]) {
      return ((float[]) collection)[i];
    } else if (collection instanceof int[]) {
      return ((int[]) collection)[i];
    } else if (collection instanceof long[]) {
      return ((long[]) collection)[i];
    } else if (collection instanceof short[]) {
      return ((short[]) collection)[i];
    } else {
      throw new ReflectionException("Cannot get the value '" + prop.getIndexedName() + "' because the property '"
          + prop.getName() + "' is not Map, List or Array.");
    }
  }

  protected void setCollectionValue(PropertyTokenizer prop, Object collection, Object value) {
    if (collection == null) {
      throw new ReflectionException("Cannot set the value '" + prop.getIndexedName() + "' because the property '"
          + prop.getName() + "' is null.");
    }
    if (collection instanceof Map) {
      ((Map) collection).put(prop.getIndex(), value);
    } else {
      int i = Integer.parseInt(prop.getIndex());
      if (collection instanceof List) {
        ((List) collection).set(i, value);
      } else if (collection instanceof Object[]) {
        ((Object[]) collection)[i] = value;
      } else if (collection instanceof char[]) {
        ((char[]) collection)[i] = (Character) value;
      } else if (collection instanceof boolean[]) {
        ((boolean[]) collection)[i] = (Boolean) value;
      } else if (collection instanceof byte[]) {
        ((byte[]) collection)[i] = (Byte) value;
      } else if (collection instanceof double[]) {
        ((double[]) collection)[i] = (Double) value;

View on GitHub (pinned to 008069adb1)

Solutions

Initialize the collection/array field where it is declared: private List<Item> items = new ArrayList<>();
Pre-size arrays before indexed assignment: items = new Item[n];
In custom result handlers, create the container (setValue of the collection itself) before setting indexed elements
Verify resultMap nested collection mappings match the target bean's initialized structure

Example fix

// before
private List<Item> items; // setValue("items[0]", x) throws

// after
private List<Item> items = new ArrayList<>();

Defensive patterns

Strategy: validation

Validate before calling

// ensure container exists before indexed writes
if (metaObject.getValue("items") == null) {
  metaObject.setValue("items", new java.util.ArrayList<>());
}
metaObject.setValue("items[0]", value);

Try / catch

try { metaObject.setValue("items[0]", v); }
catch (ReflectionException e) {
  if (e.getMessage().contains("is null")) { metaObject.setValue("items", new ArrayList<>()); metaObject.setValue("items[0]", v); }
  else throw e;
}

Prevention

Field-initialize collections: private List<X> items = new ArrayList<>();
For arrays, allocate the array before indexed writes
Verify resultMap nested mappings target initialized containers

When it happens

Trigger: Result mapping that populates 'items[0]' when the 'items' List field of the target bean is null; MetaObject.setValue("map[key]", v) when the map property was never constructed; a setter path writing into an uninitialized array property.

Common situations: DTOs with collection fields left null (no field initializer); partial result mappings that fill indexed entries before the container is created; deserialization of nested structures into beans without default constructors initializing collections.

Related errors

AI-assisted analysis of mybatis/mybatis-3@008069adb1 (2026-08-14). Data as JSON: /api/errors/4a7fa4f3a0f7b2b1. Report an issue: GitHub.