TypeError: Cannot read properties of undefined (reading 'customer')

What it means

This is the most common runtime error in JavaScript generally, and on Lambda it has a characteristic cause that makes it more tractable than it looks. A handler is a function whose only input is a JSON document produced by something you did not write — API Gateway, EventBridge, SQS, S3, a direct invoke — and every one of those produces a different shape. The error means your code walked a path through that document and fell off it.

The property named in the message is the one being read, not the one that was missing. In event.detail.customer.id, an error mentioning customer means event.detail was present and customer was not. That is a small distinction that saves a lot of time: it tells you exactly how far down the chain the shape matched before diverging.

The event-source variations that produce this most often are worth knowing by name. API Gateway delivers event.body as a string, so reading properties from it directly gives undefined rather than an error, and the failure appears one level deeper than the actual mistake. REST APIs and HTTP APIs differ in structure, and HTTP APIs have two payload format versions that put the method and path in different places. EventBridge wraps your payload under detail. SQS delivers a Records array whose body is, again, a string. A fixture built from the wrong variant passes every local test and fails on the first real request.

What makes this error frustrating to debug from raw CloudWatch is not the stack trace, which is usually precise, but the missing half of the picture: the event that caused it. Without it you can see what the code expected and not what it received. With the invocation read as a whole — the input logged at the top, your own progress lines, the throw, and the REPORT that follows — the diff between a failing request and a working one is usually visible immediately.

What it looks like in CloudWatch

This is the shape the failure arrives in: the lines of one invocation scattered among everything else the log group received at the same moment.

The panel on the right is generated by running the excerpt on the left through the same parser that powers the free web stitcher — it is what the tool actually produces for this input, not an illustration of it.

How to confirm it from the logs

The property name in parentheses tells you what was being read; the stack trace's first frame tells you where. Together they identify the exact expression, and the useful question is which part of the chain was undefined — in event.detail.customer.id, the error naming customer means event.detail existed and customer did not.

The decisive evidence is the event itself. If the function does not log its input, this error is nearly unfixable from logs alone: you can see what your code wanted and not what it got. Compare a failing invocation against a succeeding one from the same period — the difference in the events is the bug, and reading both invocations end to end is faster than reasoning about the stack.

Causes, most likely first

Fixes

jsexport const handler = async (event, context) => {
  console.log("event", JSON.stringify({
    source: event.source ?? event.requestContext?.http?.method,
    keys: Object.keys(event),
    isBase64Encoded: event.isBase64Encoded
  }));
  // ...
};

jsimport { z } from "zod";

const Order = z.object({
  customerId: z.string(),
  items: z.array(z.object({ sku: z.string(), qty: z.number().int() }))
});

export const handler = async (event) => {
  const raw = event.isBase64Encoded
    ? Buffer.from(event.body, "base64").toString()
    : event.body;

  const parsed = Order.safeParse(JSON.parse(raw ?? "{}"));
  if (!parsed.success) {
    return { statusCode: 400, body: JSON.stringify({ errors: parsed.error.issues }) };
  }
  // parsed.data is now known-good
};

js// Throws when detail is absent.
// const customer = event.detail.customer.id;

// Explicitly tolerates absence, and fails with a useful message if it matters.
const customer = event.detail?.customer?.id;
if (!customer) {
  throw new Error(`No customer id in event (keys: ${Object.keys(event).join(", ")})`);
}

Also seen as

The same underlying failure, worded differently by a different runtime, SDK version, or logging layer. All of these land here — there is no separate page for each phrasing.

Related errors

Errors that show up alongside this one, or that people mistake for it.

References

• AWS Lambda Developer Guide — Error handling in Node.js Lambda functions
• AWS Lambda Developer Guide — Using AWS Lambda with Amazon API Gateway