Mapping sourcemaps to Typescript for Lambda Debugging

Please could you elaborate on your steps/setup? Did you follow the steps from the https://docs.localstack.cloud/aws/tooling/lambda-tools/remote-debugging/?__hstc=108988063.4c622af5b27adbbb06f1ed4aaa8099e3.1764598451761.1764598451761.1764598451761.1&__hssc=108988063.1.1764598451761&__hsfp=3292877976#debugging-nodejs-lambda-functions guide? Detailed instructions on setting up your project would be appreciated.

Please note that Webstorm provides no official support for AWS lambda functions. Did you try using AWS Toolkit for WebStorm for running/debugging AWS Lambda functions as suggested in https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/welcome.html?

Hello, so the way of debugging lambdas mentioned in https://docs.localstack.cloud/aws/tooling/lambda-tools/remote-debugging/?__hstc=108988063.4c622af5b27adbbb06f1ed4aaa8099e3.1764598451761.1764598451761.1764598451761.1&__hssc=108988063.1.1764598451761&__hsfp=3292877976#debugging-nodejs-lambda-functions was the original way that I had tried debugging however I ran into the same issue and this way only allows debugging of one lambda at a time. Instead I am using localstacks new Debug Mode which is why I'm using the pro version that basically removes the need to add the LAMBDA_DOCKER_FLAGS. 

https://blog.localstack.cloud/debug-aws-lambda-functions-locally-using-localstack-debug-mode/ 

https://docs.localstack.cloud/aws/tooling/lambda-tools/remote-debugging/#lambda-debug-mode-preview 

The task setup is the same with attaching to the node process and I can confirm that it must be using --inspect-brk since the lambda when invoked halts until the mentioned customised debug port is attached to at least once.

I had originally tried the AWS Toolkit way only to find that the plugin can't be used with localstack for Jetbrains since the plugin does not allow a custom endpoint to point to localhost. There is an open issue about this: https://github.com/aws/aws-toolkit-jetbrains/issues/1883 

I am therefore hoping on getting it working properly this way with attaching to the node process since it is already half way there just it does not seem to map to the typescript files regardless of the sourcemaps being present.

Thank you.

After registering and installing all the stuff I'm still not sure how to get your sample code up and running. Should I deploy it with awslocal lambda create-function? Should the deployment zip include the .map file?Sorry for stupid questions, but I'm very new to AWS and do not have the full toolkit installed, I just have the awscli-local. And it seems to expect the full stuff to be there - when executing a function after deploying it, I get “ Internal error while executing lambda func1:None. Caused by AssignmentException: Could not start new environment: ContainerException:” error.  Can it be a permissions issue? I don't have the AWS account.

No worries, I'll put together a more comprehensive reply about the setup soon. I thought I already had replied with the response about it but must not have submitted it at the time a couple of days ago.

Thank you!

Make sure a localstack docker container has been started up, I have updated the sample project with a docker compose and lambda setup file that can be ran. The error you had got before I expect is because localstack was not up and running.

The lambda code also needs to be built using node 22.x

Setup steps

Within the project root

1. Assign your own auth token
Since we are using a localstack pro image, you need to update the docker-compose.yml file and add your own auth token, replacing the value AUTH-TOKEN-HERE

2. Start up Localstack in docker

Run: docker compose up

A localstack container will then take a minute or two to start up once docker has pulled the image

3. Install project dependencies 

Run:  npm install

Project dependencies will then be pulled and the node_modules folder appearing

4. Build the lambda code (requires node v22.x)

Run: npm run build

The dist folder will appear with the built lambda code in the src folder including the sourcemap file

5. Create the lambda in localstack

I have provided a shell script that should be ran that creates the lambda and basically mounts the built lambda code directory dist folder into an S3 bucket: ./1-create-lambda.sh

This is in line with localstack documentation for their Hot Reloading: https://docs.localstack.cloud/aws/tooling/lambda-tools/hot-reloading/#creating-the-lambda-function-with-esbuild 

6. Create the Webstorm Run Configuration

Attach to Node/Chrome

Host: localhost

Port: 5678

Remote URLs of local files
For this a single mapping is required with the project dist folder as the File/Directory and /var/task as the Remote URL

7. Set breakpoint in Lambda handler function

Add a breakpoint on any of the lines in the lambda handler function

8. Run Webstorm Configuration

Run the configuration created earlier

9. Invoke the Lambda

Invoke the lambda using command:

awslocal lambda invoke \
--function-name typescript-lambda \
--cli-binary-format raw-in-base64-out \
--payload '{"action": "test"}' \
response.json

The breakpoint will then be hit in Webstorm however not in the typescript file but in the built index.js file.

Sourcemaps are included and we are not minifying the built lambda code so I expected the the mapping of the built index.js file over to the typescript app.ts

Thank you very much for the detailed instructions!

Unfortunately it still doesn't work for me. No errors this time, but breakpoints are not hit (neither in .js nor in .ts, and the same in VSCode). When invoking lambda, I can see the following in the console:

awslocal lambda invoke --function-name typescript-lambda --payload '{"action": "test"}' 
{
   "StatusCode": 200,
   "FunctionError": "Unhandled",
   "ExecutedVersion": "$LATEST"
}

Process finished with exit code 0

and this is the output in Docker console:

localstack-main  | 2025-12-12T17:09:52.965 DEBUG --- [et.reactor-0] l.s.l.i.version_manager    : Got an invocation for function arn:aws:lambda:us-east-1:000000000000:function:typescript-lambda:$LATEST with request_id d6330cb1-3926-4416-aac2-df40f8adeafb
localstack-main  | 2025-12-12T17:09:52.965 DEBUG --- [et.reactor-0] l.s.l.i.docker_runtime_exe : Sending invoke-payload '{"invoke-id": "d6330cb1-3926-4416-aac2-df40f8adeafb", "invoked-function-arn": "arn:aws:lambda:us-east-1:000000000000:function:typescript-lambda", "payload": "'{action:", "trace-id": "Root=1-693c4c60-3675242f3d983caba19ab335;Parent=cbe798a5482acddd;Sampled=1"}' to executor '18bfa93ef235c9da9c163d4324cea51a'
localstack-main  | 2025-12-12T17:09:52.977  INFO --- [et.reactor-1] localstack.request.http    : POST /_localstack_lambda/18bfa93ef235c9da9c163d4324cea51a/invocations/d6330cb1-3926-4416-aac2-df40f8adeafb/logs => 202
localstack-main  | 2025-12-12T17:09:52.982  INFO --- [et.reactor-1] localstack.request.http    : POST /_localstack_lambda/18bfa93ef235c9da9c163d4324cea51a/invocations/d6330cb1-3926-4416-aac2-df40f8adeafb/error => 202
localstack-main  | 2025-12-12T17:09:52.985 DEBUG --- [et.reactor-0] l.s.lambda_.provider       : Lambda invocation duration: 20.17ms
localstack-main  | 2025-12-12T17:09:52.992  INFO --- [et.reactor-0] localstack.request.aws     : AWS lambda.Invoke => 200

I can't see console.log() output from lambda anywhere. I must be doing something wrong.  may be the issue is that I'm on Windows, I had to adapt your steps to work there.

Your lambda invocation command is incorrect, can you confirm with:

awslocal lambda invoke \
--function-name typescript-lambda \
--cli-binary-format raw-in-base64-out \
--payload '{"action": "test"}' \
response.json

You will get an error if --cli-binary-format raw-in-base64-out is not included mentioned in https://stackoverflow.com/a/61242201 

I tried it, but got 

Unknown options: --cli-binary-format, test}'

The AWS CLI version must be the issue, I installed it with pip install awscli-local[ver1] as suggested at https://github.com/localstack/awscli-local

Yes, I expect your AWS CLI is v2 but the AWS Local CLI is v1 so it won't recognise that parameter. Can you uninstall the awscli-local and install again without specifying the [ver1]? I've been using:

pip3 install awscli-local

Also confirm that AWS CLI v2 is installed via:

aws --version

Which should reveal something like:

aws-cli/2.7.21 Python/3.9.11 Darwin/25.0.0 exe/x86_64 prompt/off

What is the status of the investigation into this?

After further investigation, I have managed to resolve the issue with sticking to tsc for compilation. The problem was a combination of missing Remote URL mapping and how the lambda code was being built:

Remote URL Mapping

• Two mappings instead of one required:
  1. Build directory: ./dist mapped to /var/task/dist
  2. Source directory: ./src mapped to /var/task/src

TSC compilation

A simplified version of the tsconfig.json that was used to make sure the build directory mappings are correct:

{
  "compilerOptions": {
    "resolveJsonModule": true,
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "node",
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "inlineSources": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true,
    "baseUrl": "./src"
  },
  "include": ["src/**/*.ts"]
}

There was then a slight change I needed to do on the localstack side when uploading the lambda with pointing the code source to the root of the project where the node_modules folder was included so that the dependencies are accessible (no bundling). The lambda handler location was then pointed to the build directory.

I'd like to try get this to work using ESBuild instead of TSC so I can use a hybrid approach (tsc for type checking and esbuild for JS transpilation) which I'm looking into now. For the moment though this works for a pure TSC approach.