Runtime.HandlerNotFound: index.handler is undefined or not exported

What it means

A Lambda handler configuration is two pieces of information joined by a dot: which file to load, and which exported name to call inside it. Runtime.HandlerNotFound means the first half succeeded and the second half did not. The file was located and executed; the name was not found on what it exported.

That distinction is genuinely useful, because it eliminates a whole class of suspects immediately. If the deployment package were missing, or the path wrong, you would be looking at Runtime.ImportModuleError instead. Getting HandlerNotFound proves the artifact contains the file, that the file parsed, and that it ran to completion. The problem is narrower than it feels: something about the export.

In practice it is nearly always one of two things. The names disagree — usually because an export was renamed and the deployment configuration was not, or because a bundler emits to a different filename than the source. Or the module systems disagree: a file using ESM export syntax loaded by the CommonJS loader does not present handler where the runtime looks, and the mirror-image mismatch behaves the same way. The .mjs and .cjs extensions and the type field in package.json are what decide which loader runs, and they are easy to get subtly wrong in a monorepo where one package sets "type": "module" and another does not.

Because this is an init failure, its blast radius is total and its logs are sparse. Every invocation on every container fails the same way, none of your code runs, and there is nothing in the log but the runtime's own complaint. The one line that matters is the one naming file.export, and matching it against what the artifact actually exports resolves it almost every time.

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 message names exactly what Lambda looked for, in file.export form. index.handler means it loaded index.js (or .mjs/.cjs) and looked for an export called handler. That the error mentions the file at all is the important signal: if the file were missing you would get Runtime.ImportModuleError instead. Getting this error proves the file was found.

Like every init failure it appears before any of your own logging and repeats identically on every invocation. Check the REPORT line for Error Type: Runtime.HandlerNotFound where the runtime writes it.

Causes, most likely first

Fixes

yamlResources:
  ApiFunction:
    Type: AWS::Serverless::Function
    Properties:
      # src/handlers/orders.js exporting `handler`
      Handler: src/handlers/orders.handler
      Runtime: nodejs22.x

js// ESM — file is .mjs, or package.json has "type": "module"
export const handler = async (event) => {
  return { statusCode: 200 };
};

// CommonJS — file is .cjs, or package.json has no "type": "module"
// exports.handler = async (event) => ({ statusCode: 200 });

bashnode -e "import('./dist/index.js').then(m => console.log(Object.keys(m)))"

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 — Define Lambda function handler in Node.js
• AWS Lambda Developer Guide — Troubleshoot deployment issues