Trouble specifying handler with index.mjs file in Lambda function running Node.js 20

Question

Hi,
I'm currently updating my Lambda function from Node.js 16 to Node.js 20. As part of this update, I'm transitioning to using the **index.mjs** file instead of index.js. However, I'm encountering difficulties in specifying the handler when using **index.mjs.**

I've tried setting the handler to index.mjs.handler, but it results in the following error:

```
{
  "errorType": "Runtime.HandlerNotFound",
  "errorMessage": "index.mjs.handler is undefined or not exported",
  "trace": [
    "Runtime.HandlerNotFound: index.mjs.handler is undefined or not exported",
    "    at UserFunction.js.module.exports.load (file:///var/runtime/index.mjs:1122:15)",
    "    at async start (file:///var/runtime/index.mjs:1282:23)",
    "    at async file:///var/runtime/index.mjs:1288:1"
  ]
}
```
I've also attempted to specify the module type in package.json, with the hope it would select **index.mjs** but it just runs** index.js**.

Is there a recommended approach for specifying the handler when using an index.mjs file in a Lambda function running Node.js 20? My goal is to maintain both **index.js** and **index.mjs ** files without renaming them, and easily switch between them if needed.

Any insights or guidance would be greatly appreciated.

Thanks!

Answer

Hello,

By default, Lambda treats files with the .js suffix as CommonJS modules. Optionally, you can designate your code as an ES module. You can do this in two ways: specifying the type as module in the function's package.json file, or by using the .mjs file name extension. In the first approach, your function code treats all .js files as ES modules, while in the second scenario, only the file you specify with .mjs is an ES module. You can mix ES modules and CommonJS modules by naming them .mjs and .cjs respectively, as .mjs files are always ES modules and .cjs files are always CommonJS modules.

For Node.js runtime versions up to Node.js 16, the Lambda runtime loads ES modules from the same folder as your function handler, or a subfolder. Starting with Node.js 18, Lambda searches folders in the NODE_PATH environment variable when loading ES modules. Also, starting with Node.js 18, you can load the AWS SDK that's included in the runtime using ES module import statements. You can also load ES modules from layers.

[+] Building Lambda functions with Node.js - Designating a function handler as an ES module - https://docs.aws.amazon.com/lambda/latest/dg/lambda-nodejs.html#designate-es-module

Additionally, with regards to `My goal is to maintain both index.js and **index.mjs** files without renaming them, and easily switch between them if needed.` You can consider using Lambda function version and aliasis. When you publish a Lambda function version, its code, runtime, architecture, memory, layers, and most other configuration settings are immutable.

[+] Lambda function versions - https://docs.aws.amazon.com/lambda/latest/dg/configuration-versions.html
[+] Lambda function aliases - https://docs.aws.amazon.com/lambda/latest/dg/configuration-aliases.html

Trouble specifying handler with index.mjs file in Lambda function running Node.js 20

Relevant content