"direct-invoke" debugging of SAM (lambda) app with Image package type fails
- 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
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