Skip to content

fix(layers): do not ship AWS SDK clients in the Lambda layer #5512

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
svozza wants to merge 3 commits into
base: main
Choose a base branch
from
+29 −15
Open

fix(layers): do not ship AWS SDK clients in the Lambda layer #5512

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1cbc261
fix(layers): do not ship AWS SDK clients in the Lambda layer
svozza Jul 28, 2026
cd65aa3
docs(layers): stop telling customers to exclude @aws-sdk/* from bundles
svozza Jul 28, 2026
f17cefb
docs(layers): note that the layer no longer bundles the AWS SDK
svozza Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 16 additions & 6 deletions docs/getting-started/lambda-layers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,15 +154,14 @@ Change `{aws::region}` to your AWS region, e.g. `eu-west-1`, and run the followi
}
```

If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` and `@aws-sdk/*` from being bundled since the packages are already present the layer:
If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` from being bundled since the packages are already present in the layer:

```typescript
new NodejsFunction(this, 'Function', {
...
bundling: {
externalModules: [
'@aws-lambda-powertools/*',
'@aws-sdk/*',
],
}
});
Expand Down Expand Up @@ -223,7 +222,7 @@ Change `{aws::region}` to your AWS region, e.g. `eu-west-1`, and run the followi
- {{resolve:ssm:/aws/service/powertools/typescript/generic/all/latest}}
```

If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` and `@aws-sdk/*` from being bundled since the packages are already present the layer:
If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` from being bundled since the packages are already present in the layer:

```yaml hl_lines="5-14"
MyLambdaFunction:
Expand All @@ -237,7 +236,6 @@ Change `{aws::region}` to your AWS region, e.g. `eu-west-1`, and run the followi
Minify: true
External:
- '@aws-lambda-powertools/*'
- '@aws-sdk/*'
```

Check the [documentation](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-build-typescript.html) for more details.
Expand All @@ -252,14 +250,13 @@ Change `{aws::region}` to your AWS region, e.g. `eu-west-1`, and run the followi
- arn:aws:lambda:${aws:region}:094274105915:layer:AWSLambdaPowertoolsTypeScriptV2:49
```

If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` and `@aws-sdk/*` from being bundled since the packages are already present the layer:
If you use `esbuild` to bundle your code, make sure to exclude `@aws-lambda-powertools/*` from being bundled since the packages are already present in the layer:

```yaml
custom:
esbuild:
external:
- '@aws-lambda-powertools/*'
- '@aws-sdk/*'
```

Check the [documentation](https://floydspace.github.io/serverless-esbuild/) for more details.
Expand Down Expand Up @@ -364,3 +361,16 @@ npm i -D @aws-lambda-powertools/logger
- **Version synchronization**: Keep your local development dependencies in sync with the Lambda Layer version to maintain consistency

Following these practices prevents version conflicts that can cause unexpected behavior, such as failed `instanceof` checks or inconsistent behavior between your local development environment and the Lambda execution environment.

???+ note "AWS SDK v3 is no longer included in the layer"

Layer version `49` is the last one to bundle AWS SDK v3 clients; later
versions do not include any `@aws-sdk/*` package.

The layer is mounted at `/opt/nodejs/node_modules`, which takes precedence
over the runtime's own copy, so the bundled clients were picked up by your
function code as well. Since the layer only ever included a subset of the
SDK, this could leave you with mismatched SDK packages at runtime.

Install the clients your code needs as regular dependencies and bundle them
with your function, or rely on the copy the Lambda Node.js runtime provides.
22 changes: 13 additions & 9 deletions layers/src/layer-publisher-stack.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,15 +107,19 @@ export class LayerPublisherStack extends Stack {
'node_modules/@aws-sdk/**/README.md ',
];
const buildCommands: string[] = [];
// We install these to get the latest version of the packages
const modulesToInstall: string[] = [
'@aws-sdk/client-dynamodb',
'@aws-sdk/util-dynamodb',
'@aws-sdk/client-ssm',
'@aws-sdk/client-secrets-manager',
'@aws-sdk/client-appconfigdata',
'zod',
];
// We deliberately do NOT ship any @aws-sdk/* client in the layer.
//
// The layer is mounted at /opt/nodejs/node_modules, which precedes
// /var/runtime/node_modules on NODE_PATH. Any SDK package we ship
// therefore shadows the runtime's copy for customer code too. Since
// we only ever shipped a subset (e.g. client-dynamodb but never
// lib-dynamodb), customers using the DocumentClient ended up with a
// layer-provided client and a runtime-provided lib, and any breaking
// change across that boundary surfaces as a runtime error.
//
// The Node.js runtime already provides a complete, self-consistent
// AWS SDK v3, so we rely on it instead of exposing a partial one.
const modulesToInstall: string[] = ['zod'];

if (buildFromLocal) {
for (const util of utilities) {
Expand Down
Loading