Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

AWS Lambda fails on 'export' because Node treats the file as CommonJS

ErrorSyntaxError: Unexpected token 'export'

Short answer

Lambda runs a .js file as CommonJS unless told otherwise, and CommonJS has no export keyword. Rename the handler file to .mjs, or add "type": "module" to the function's package.json. On Node.js 22 and 24 you can also enable module detection with a NODE_OPTIONS flag, but AWS marks it experimental.

  • Applies to Node.js 22 runtime, Node.js 24 runtime
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List the files in the deployment package and read its package.json. You need to see the handler file's extension and whether a type field exists.

    unzip -l function.zip | head -20
    unzip -p function.zip package.json
  2. 2Match what you see, then jump to its fix

    1. 1The file ends in .js, uses export const handler, and package.json has no type fieldThe handler file is .js and nothing marks it as an ES moduleFix
    2. 2You want to keep the .js extension (bundler output, shared code), and the imports and exports are ES syntaxpackage.json does not declare the module typeFix
    3. 3The code base is shared with another runtime and mixes syntaxesYou cannot change file names or package.json and run Node.js 22 or 24Fix

What does the error look like?

  • SyntaxError: Unexpected token 'export'

Cause 1 of 3

The handler file is .js and nothing marks it as an ES module

1Check

Node.js treats .js files as CommonJS by default, and only .mjs files as ES modules.

unzip -l function.zip | grep -E "index\.(js|mjs)"

2Fix

Rename the file to index.mjs. The Handler setting stays index.handler, because it is the file name without extension plus the exported name.

mv index.js index.mjs
zip -r function.zip index.mjs node_modules package.json

3Verify

Upload the package, run a test event, and check the logs have no syntax error.

aws lambda update-function-code --function-name my-function --zip-file fileb://function.zip

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 3

package.json does not declare the module type

1Check

You can make Node.js treat .js files as ES modules by setting type to module in the function's package.json.

unzip -p function.zip package.json | grep '"type"'

2Fix

Add the type field to the package.json that is packaged with the function.

{
  "name": "my-function",
  "type": "module"
}

3Verify

Redeploy and invoke; the test event runs and the log shows no syntax error.

aws lambda invoke --function-name my-function out.json && cat out.json

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 3

You cannot change file names or package.json and run Node.js 22 or 24

1Check

Lambda starts these runtimes with module detection turned off. The documentation lists the flag that turns it back on.

aws lambda get-function-configuration --function-name my-function --query Environment

2Fix

Set NODE_OPTIONS to --experimental-detect-module on the function. AWS warns that experimental features can cause instability and are not covered by the Lambda SLA, so prefer the first two fixes.

aws lambda update-function-configuration --function-name my-function --environment "Variables={NODE_OPTIONS=--experimental-detect-module}"

3Verify

Invoke the function and check the log for the syntax error.

aws lambda invoke --function-name my-function out.json

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Write new Lambda handlers as index.mjs with export const handler.
  • Move to a supported runtime: Node.js 14 is no longer in the list of supported Lambda Node.js runtimes.
  • Keep one module style per function and test the zip with a real invoke before release.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

API Gateway gives up on a slow Lambda or Node.js backend

$context.integrationErrorMessage in the access log shows the integration error

API Gateway stops waiting for the backend at its integration timeout: 29 seconds by default on REST APIs, a fixed 30 seconds on HTTP APIs.

4 causes, each with a fix

Back end

cdk synth says --app is required

--app is required either in command-line, in cdk.json or in ~/.cdk.json

The CDK CLI needs a command that runs your app and finds it in three places: the --app option, cdk.json in the project folder, or cdk.json in your home folder.

3 causes, each with a fix

Back end

The AWS SDK in Node.js cannot find any credentials

Missing credentials in config, if using AWS_CONFIG_FILE, set AWS_SDK_LOAD_CONFIG=1

The AWS SDK walks a fixed credential chain: code, environment variables, the shared files in ~/.aws, then role sources such as ECS or EC2.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.