Introduction

The error Cannot deserialize instance of java.lang.String out of START_OBJECT means your Java code expects a plain string, but the JSON payload actually contains an object at that location. This shows up often in AWS Lambda handlers, API integrations, and SDK-based services because JSON contracts move across many layers and it is easy for the Java model to drift away from the real payload shape.

What the error is telling you

JSON has different token types. A string looks like "hello", while an object begins with { and contains named fields. If Jackson is asked to fill a Java field of type String and the incoming token is an object start, deserialization stops with this error.

A minimal broken example looks like this:

1{
2  "customerId": "42",
3  "metadata": {
4    "source": "web",
5    "campaign": "spring"
6  }
7}

1public class OrderRequest {
2    private String customerId;
3    private String metadata;
4
5    public String getCustomerId() {
6        return customerId;
7    }
8
9    public void setCustomerId(String customerId) {
10        this.customerId = customerId;
11    }
12
13    public String getMetadata() {
14        return metadata;
15    }
16
17    public void setMetadata(String metadata) {
18        this.metadata = metadata;
19    }
20}

The Java model says metadata is a string, but the JSON sends an object. Jackson cannot invent a sensible conversion, so it fails.

Fix the model so it matches the payload

When the JSON is correct, the fix is to change the Java field type.

1public class OrderRequest {
2    private String customerId;
3    private Metadata metadata;
4
5    public String getCustomerId() {
6        return customerId;
7    }
8
9    public void setCustomerId(String customerId) {
10        this.customerId = customerId;
11    }
12
13    public Metadata getMetadata() {
14        return metadata;
15    }
16
17    public void setMetadata(Metadata metadata) {
18        this.metadata = metadata;
19    }
20}
21
22public class Metadata {
23    private String source;
24    private String campaign;
25
26    public String getSource() {
27        return source;
28    }
29
30    public void setSource(String source) {
31        this.source = source;
32    }
33
34    public String getCampaign() {
35        return campaign;
36    }
37
38    public void setCampaign(String campaign) {
39        this.campaign = campaign;
40    }
41}

This is the cleanest solution because it preserves the actual structure of the data instead of flattening everything into strings.

AWS-specific places this appears

In AWS, this error often appears in a few recurring situations:

• A Lambda handler expects a plain field, but API Gateway or EventBridge sends a nested object.
• An SNS or SQS message body contains JSON as a string, and the code treats it as already-parsed nested fields.
• A request model was copied from an older version of the payload and no longer matches the live schema.

For example, API Gateway proxy events often put the HTTP body inside a string field named body. That means the outer event deserializes first, then you parse body separately if it contains nested JSON. Trying to map the entire event directly into your business model is a common source of confusion.

Debugging the mismatch quickly

The fastest way to debug this class of error is to log the raw payload and compare it directly with your Java class. Do not trust memory or old documentation. Look at the exact JSON your function received.

If the payload is nested but your model uses String, int, or some other scalar type, the mismatch is obvious. If the payload wraps data in an envelope such as detail, body, or Message, you may need one more Java class level than you expected.

If you truly want the raw nested object as text, you can deserialize into JsonNode or Map and convert later, but that should be a deliberate choice rather than a workaround for a wrong model.

Common Pitfalls

One common mistake is double-encoding JSON. A system may send a JSON string that itself contains JSON text. In that case, one stage expects a string and another stage expects an object. Be clear about which layer you are parsing.

Another problem is assuming that AWS service wrappers match your domain model directly. Event payloads usually include metadata, envelopes, and service-specific field names before you reach the part you care about.

Developers also forget to update model classes when the producer changes the contract. Adding one nested object field on the producer side is enough to trigger this error on the consumer side.

Finally, avoid papering over the issue by converting everything to String. That throws away type safety and usually makes the next bug harder to diagnose.

Summary

• The error means Java expected a String but the JSON token was an object.
• Fix the Java field type so it matches the actual payload shape.
• In AWS systems, check for wrapper objects such as body, detail, or Message.
• Log the raw event before changing code so you can compare model and payload directly.
• Use structured classes, JsonNode, or Map deliberately rather than flattening nested JSON into strings.