Error: could not unconvert attribute dynamodb

could not unconvert attribute means the Java SDK 1.x DynamoDBMapper failed while turning a stored attribute into a Java property. Read the deepest exception first: a type mismatch, custom converter failure, or bean-construction problem needs a different fix.

Find the attribute that fails

1. Capture the complete exception chain and the attribute or property name. A number parser failure points to the stored value; a construction or reflection failure points to the model class.
2. Read the failing item with the low-level client or CLI so the mapper does not hide its DynamoDB types. Compare the attribute with the Java getter, setter and converter.
3. Check older items as well as recent writes. A property changed from a String to a document map does not migrate data already stored in the table.

aws dynamodb get-item --table-name People \
  --key '{"id":{"S":"person-1"}}' --consistent-read

Repair the model or stored representation

For a mutable bean, provide an accessible no-argument constructor and matching public getters and setters. A nested class used as a model should be static. The getter and setter types must agree; use a nullable wrapper such as Integer when missing values are meaningful. Lombok-generated methods still need to satisfy these rules.

For a custom DynamoDBTypeConverter, inspect unconvert() and test it with the exact stored value. Its input representation must match what convert() wrote. Fix the converter or migrate incompatible records; adding a constructor cannot repair a malformed number or an unexpected map.

Current Java mapping equivalent

For new code, use the AWS SDK for Java 2.x Enhanced Client. The annotations below belong to v2; they are not a drop-in change for an existing v1 mapper.

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;

@DynamoDbBean
public class Person {
    private String id;
    private Integer age;
    public Person() {}
    @DynamoDbPartitionKey
    public String getId() { return id; }
    public void setId(String id) { this.id = id; }
    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }
}

Map this class with TableSchema.fromBean(Person.class). For custom types, use an AttributeConverter and @DynamoDbConvertedBy, or configure a converter provider. Keep the stored representation compatible during migration.

See Java mapping examples and AWS documentation.

Enhanced Client conversion reference describes the current converter API.