Bug: Cannot attach to debugger for Apple ARM-Based Chip in VS Code

[hungnvo]

Description:

When attempting to attach a debugger to a locally running AWS Lambda function using the SAM CLI on an Apple ARM-based chip (e.g., M1/M2), the debugger keep hanging and never attached. My guess is potentially due to compatibility issues between the debugger, SAM CLI, and Docker on the ARM architecture.

Steps to reproduce:

1. Create new directory

mkdir -p ~/.vsdbg

2. Use Docker to download and install vsdbg for the AWS Lambda runtime container with .NET 6 and copy it to local machine

docker run --rm --mount type=bind,src=~/.vsdbg,dst=/vsdbg --entrypoint bash lambci/lambda:dotnet6.0 -c "curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v latest -l /vsdbg"

3. Build SAM

sam build

4. SAM local start api

sam local start-api --port 1111 --skip-pull-image --debug-port 5858 --debugger-path ~/.vsdbg --warm-containers EAGER

5. Start launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Docker Attach",
      "type": "coreclr",
      "request": "attach",
      "processId": "1",

      "pipeTransport": {
        "pipeProgram": "sh",
        "pipeArgs": [ 
          "-c",
          "docker exec -i $(docker ps -q -f publish=5858) ${debuggerCommand}"
        ],
        "debuggerPath": "/tmp/lambci_debug_files/vsdbg",
        "pipeCwd": "${workspaceFolder}",
      },
      "sourceFileMap": {
        "/var/task": "${workspaceFolder}"
      }
    }
  ]
}

I attempted to try both run the launch.json file before and after hitting the endpoint to see if it makes any different.

Observed result:

No breakpoint were hit. the debugger keep hanging and never actually attached.

Expected result:

It will actually hit the breakpoints.

Additional environment details (Ex: Windows, Mac, Amazon Linux etc)

1. OS: MacOS Apple M3
2. sam --version: 1.132
3. Lambda Runtime: dotnet6

{
  "version": "1.132.0",
  "system": {
    "python": "3.13.1",
    "os": "macOS-15.2-arm64-arm-64bit-Mach-O"
  },
  "additional_dependencies": {
    "docker_engine": "27.3.1",
    "aws_cdk": "Not available",
    "terraform": "Not available"
  },
  "available_beta_feature_env_vars": [
    "SAM_CLI_BETA_FEATURES",
    "SAM_CLI_BETA_BUILD_PERFORMANCE",
    "SAM_CLI_BETA_TERRAFORM_SUPPORT",
    "SAM_CLI_BETA_RUST_CARGO_LAMBDA"
  ]
}

[roger-zhangg]

Thanks for reporting, to better understand this issue. If you run sam local invoke to invoke the .Net 6 function, will it also hang, or it only happens when you sam local start-api and try to attach a debugger?

[hungnvo]

@roger-zhangg The problem is that I want to use sam local start-api so that i don't have to supply the event.json payload for request instead I just need to use Postman to send the request. if I have to create myself a event.json payload, then I can just use the Mocked Lambda Test Tools and it worked just fine for me.

[vicheey]

Thank you for the additional information. While we investigate the issue, you may try local invoke and debugging your Lambda functions using AWS Toolkit extension. You can load and save your test event for local invoke right inside of VS Code.

https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/setup-toolkit.html

[dcabib]

Hey everyone,

I was able to reproduce this issue on my M1 MacBook Pro running macOS and SAM CLI.

After some digging, I think I found what's causing the debugger to hang. The root cause seems to be an architecture mismatch between the vsdbg binary and the Lambda container.

What's happening:

When we download vsdbg using the Microsoft install script on an ARM Mac, the script detects the host architecture (ARM64) and downloads the ARM64 version of vsdbg. However, the Lambda container runs as x86_64 by default. Looking at SAM CLI source code (samcli/lib/build/utils.py), when no architecture is specified in template.yaml, it defaults to x86_64:

def _get_function_architecture(function: Function) -> str:
    """
    Get function architecture, defaulting to x86_64.
    """
    if function.architectures:
        return function.architectures[0]
    return X86_64  # <-- default

So we end up with an ARM64 vsdbg binary trying to run inside an x86_64 container, which causes the classic "no such file or directory" error from the dynamic linker - but since it happens silently inside the container, all we see is the debugger hanging.

You can verify this by running:

file ~/.vsdbg/vsdbg
# Shows: ARM aarch64

Then running vsdbg inside the container manually:

docker exec -it <container_id> /tmp/lambci_debug_files/vsdbg --help
# Fails silently or shows "no such file or directory"

Possible solution:

One approach could be for SAM CLI to detect the debugger binary architecture before mounting it into the container, and if there'''s a mismatch with the target architecture, either:

1. Warn the user about the mismatch and suggest downloading the correct version
2. Auto-download the correct version using Docker with --platform linux/amd64 to force the correct architecture
3. Cache the downloaded debuggers per architecture to avoid repeated downloads

The tricky part is that the download script (aka.ms/getvsdbgsh) auto-detects the platform, so we'''d need to run it inside a container with the correct platform to get the right binary.

I'd be happy to help with a PR if you think this approach makes sense. Let me know your thoughts.