aws / aws/aws-toolkit-vscode

"direct-invoke" debugging of SAM (lambda) app with Image package type fails

Open
#8,460 1 comment 0 reactions 0 assignees View on GitHub
bug
Dominant language
TypeScript
Stars
2k
Forks
807
Avg merge
10h 12m
Merged PRs (30d)
7

Description

## Problem

Using the "Hello World Example" created by `sam init`, selecting python3.13 runtime and image package type as opposed to ZIP. The `direct-invoke` debug configuration you can generate using CodeLens from the template.yaml then does not work. The problem seems to be with quotes around debug-args in the command generated by AWS Toolkit. I found a workaround.

## Steps to reproduce the issue

1. Create the Hello World Example as above.
2. Go to template.yaml and accept the CodeLens suggestion (you may need to turn CodeLens on) to create a debug configuration in launch.json which will look like this:

```jsonc
{
"type": "aws-sam",
"request": "direct-invoke",
"name": "sam-app:HelloWorldFunction (python3.13)",
"invokeTarget": {
"target": "template",
"templatePath": "${workspaceFolder}/sam-app/template.yaml",
"logicalId": "HelloWorldFunction"
},
"lambda": {
"payload": {},
"environmentVariables": {},
"runtime": "python3.13"
}
}
```
3. `sam build` which should succeed
4. Run the debug configuration, it fails like this:

```text
2025-12-22 15:47:35.967 [info] File "/var/lang/bin/python3.13", line 1
ELF
SyntaxError: source code cannot contain null bytes
```

## Expected behavior

The code should run on your local Docker and the Vscode debugger should stop on any breakpoint you have set.

## Why does it fail?

You can see in AWS Toolkit logs the `sam local invoke` command the Toolkit is generating, along with its arguments:

```text
2025-12-22 16:43:47.308 [info] Command: (not started) [C:\Program Files\Amazon\AWSSAMCLI\bin\sam.cmd local invoke HelloWorldFunction --template C:\Users\MYUSER\AppData\Local\Temp\aws-toolkit-vscode\vsctk57e7b8b2\output\template.yaml -d 5858 --skip-pull-image --debugger-path c:\Users\myuser\.vscode\extensions\amazonwebservices.aws-toolkit-vscode-3.91.0\resources\debugger --debug-args /var/lang/bin/python3.13 /tmp/lambci_debug_files/py_debug_wrapper.py --listen 0.0.0.0:5858 --wait-for-client --log-to-stderr /var/runtime/bootstrap.py --region us-east-1 --runtime python3.13]
```

The problem seems to be the --debug-args need quotes around them. Without them, the command `python /var/lang/bin/python3.13' is being fed to the container, so the python (ELF) binary is being treated as if it were a source file.

If instead you use the above to build a command you can use yourself at the terminal, including quotes around the --debug-args and removing --template so it uses your template.yaml directly:

`sam local invoke HelloWorldFunction -d 5858 --skip-pull-image --debugger-path c:\Users\myuser\.vscode\extensions\amazonwebservices.aws-toolkit-vscode-3.91.0\resources\debugger --debug-args "/var/lang/bin/python3.13 /tmp/lambci_debug_files/py_debug_wrapper.py --listen 0.0.0.0:5858 --wait-for-client --log-to-stderr /var/runtime/bootstrap.py --region us-east-1 --runtime python3.13"`

The code will run successfully and pause with:

```text
Debugger waiting for client...
```

If you then use a Vscode debug configuration like this, you can run it and attach the debugger to the paused session, debugging then works.

```jsonc
{
"name": "Python: Attach to SAM Local",
"type": "debugpy",
"request": "attach",
"connect": {
"host": "localhost",
"port": 5858
},
"pathMappings": [
{
"localRoot": "${workspaceFolder}/sam-app/hello_world",
"remoteRoot": "/var/task"
}
]
}
```

## System details (run `AWS: About` and/or `Amazon Q: About`)

- OS: Windows 11
- Visual Studio Code version: 1.107.0
- AWS Toolkit version: 3.91.0
- AWS SAM CLI version: 1.151.0

Contributor guide

Open the contributing guide

Research direction

Reproduce the generated configuration from template.yaml and launch.json, then inspect how the AWS Toolkit constructs the sam local invoke command and its --debug-args value. Compare that command with the quoted terminal workaround; done means direct-invoke starts the local Docker session and allows the VS Code debugger to stop at breakpoints.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, docker, python, typescript, vscode
Domain
cloud, developer-experience, devtools
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.