Troubleshooting¶

Errors are printed as [category] message, usually with a Hint: line. The category tells you which stage failed and what has already happened in AWS.

validation¶

The YAML is invalid, a key is unknown or misspelled, a value has the wrong type, or the target doesn't exist. The message names each failing key. For a misspelt entry:

[validation] Invalid config /path/to/lambda-dev.yml: targets.dev.build.entry: Invalid input: expected string, received undefined; targets.dev.build: Unrecognized key: "entri"

Nothing has been sent to AWS.

npx aws-lambda-dev validate

filesystem¶

The config file couldn't be read. Check the path, or pass --config.

build¶

esbuild failed, a build.copy entry is invalid, or the zip is over Lambda's 50 MB limit for direct uploads. For a large zip, leave dependencies the runtime already has out of the bundle with build.external (such as @aws-sdk/*), turn on build.minify, or move large files to a layer. The upload and invoke are skipped. In watch mode, fix the error and save again.

aws_snapshot¶

The CLI couldn't save the function's current code and environment before its first deploy, so it stopped without changing anything. Common causes:

• Missing lambda:GetFunction permission.
• No access to the KMS key the function's environment is encrypted with.
• The function is a container image, which this tool doesn't deploy.
• The function's current code is over 50 MB zipped, more than rollback could upload.

The same causes apply when a deploy with checks or invoke.expect saves the function's current state for automatic rollback.

Fix the cause and deploy again, or set snapshot: false on the target to deploy without a snapshot (and --no-rollback to deploy without an automatic rollback). See Rollback.

aws_configuration¶

Reading or updating environment variables failed, or the function didn't reach a ready state within 120 seconds. Common causes:

• Missing lambda:GetFunctionConfiguration or lambda:UpdateFunctionConfiguration permission.
• No access to the KMS key the function's environment is encrypted with.
• The function is mid-update from another tool or deploy.
• PreconditionFailedException: someone changed the function's configuration between the read and the write. Nothing was overwritten; rerun.
• The variables would exceed Lambda's 4 KB limit.

A previous step may already have completed, so check the function's state in the console before retrying.

aws_deploy¶

The code upload failed. Usually credentials, region, function name, or a missing lambda:UpdateFunctionCode permission. If credentials couldn't be loaded at all, the hint names the profile to check; for SSO profiles, run aws sso login --profile <name> first. If the target has environment, the environment update may already have been applied.

PreconditionFailedException means the function changed between this deploy's environment update and its code upload, usually because someone else deployed to it at the same time. Your code wasn't uploaded, so nothing was silently overwritten, but your environment changes were applied. Check the function's current state, then rerun.

aws_invoke¶

Invoking failed, usually because of a missing lambda:InvokeFunction permission. If the function ran and threw an error, that isn't reported here unless an expectation is set: the invoke summary shows functionError Unhandled instead.

It's also reported when a response doesn't match a check or invoke.expect. Each mismatch is printed with its location, such as payload.statusCode: expected 200, received 500. After deploy, the function is rolled back to how it was before that deploy, unless --no-rollback or rollbackOnFailure: false is set; the hint says which happened. If you're sending an event that should get a different response, pass --no-expect.

Watch doesn't react to changes¶

• The file must match a watch.include glob and not match watch.exclude.
• Globs are relative to the config file's directory.
• Changes to watch settings need a restart.

The function can't find its handler¶

The zip has index.js at its root, so set the function's Handler to index.<export>, e.g. index.handler.