Runtime.UnhandledPromiseRejection: TypeError: Cannot read properties of undefined

What it means

A rejected promise carries an error to whoever is waiting for it. When nobody is waiting, Node has no one to hand it to, and since version 15 the default response is to treat that as fatal: the process raises unhandledRejection and terminates. Lambda's Node runtime catches this and reports the invocation as failed with Runtime.UnhandledPromiseRejection.

The wrapper is the problem when you are debugging. Runtime.UnhandledPromiseRejection describes the handling, not the fault — it says only that nothing caught the error. The error itself sits nested inside the envelope, under reason, with its own type, message and stack. That is the one worth reading, and it is easy to skim past because the outer message repeats a truncated version of it and the whole envelope arrives as one very long JSON line.

The genuinely hard version of this bug is the one where the rejection is not attributable to the invocation you are looking at. A promise created and abandoned during invocation A can reject milliseconds later, by which time the execution environment has been frozen and thawed for invocation B — and it is invocation B that fails. The stack trace points at code that had nothing to do with the request that died. This is precisely why grouping every line of an invocation together matters more here than almost anywhere else: the rejection's stack, the last thing invocation A logged, and the failure recorded against invocation B are three facts that only make sense next to each other.

The prevention is unglamorous and works: every promise is awaited or has a .catch(). The common leaks are the ones that feel harmless at the time — a metric publish nobody waits for, an async callback handed to forEach, a cache warm started at module scope. None of them look like error handling gaps, and all of them are.

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 runtime writes an Unhandled Promise Rejection envelope as a single JSON line containing errorType, errorMessage and a stack or reason array. Read the inner error inside it: the outer Runtime.UnhandledPromiseRejection tells you only that nothing caught it, while the inner one names what actually went wrong.

The most useful thing to check is where the stack points. A stack frame inside your handler is the easy case. A stack that contains only runtime frames, or the phrase "the promise rejected with the reason", means the rejection came from a promise created outside the handler's await chain — a fire-and-forget call — and the invocation that fails may not be the one that started it.

Causes, most likely first

Fixes

js// Rejects into nothing — fails a later invocation, with a confusing stack.
// publishMetric(name, value);

// Deliberately fire-and-forget, and says so.
void publishMetric(name, value).catch((error) => {
  console.warn("metric publish failed", { name, error: error.message });
});

js// The promise returned by the callback is thrown away.
// records.forEach(async (record) => { await save(record); });

// Sequential, and every rejection propagates to the handler.
for (const record of records) {
  await save(record);
}

// Or parallel, still awaited.
await Promise.all(records.map((record) => save(record)));

jsconst results = await Promise.allSettled(
  targets.map((target) => notify(target))
);

const failed = results.filter((result) => result.status === "rejected");
if (failed.length > 0) {
  console.error("some notifications failed", {
    failed: failed.length,
    total: results.length
  });
}

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
• Node.js — process.on('unhandledRejection')