Debugging Node.js with serverless-offline v4 Fails Due to Go Binary Interference

[danilevy1212]

Bug Report

Current Behavior

When trying to set up a debugging session with Node.js using serverless-offline and serverless v4, the process fails to attach the debugger correctly. This issue occurs because serverless v4 spawns a binary as a child process that does not propagate the --inspect flag to the sf-core.js process it will spawn in return (see images below). As a result, the debugger attaches to the parent process instead of the handler code, making it impossible to debug the actual Lambda function.

Sample Code

• file: serverless.yml

# "org" ensures this Service is used with the correct Serverless Framework Access Key.
org: <my-org>
# "app" enables Serverless Framework Dashboard features and sharing them with other Services.
app: hello-app
# "service" is the name of this project. This will also be added to your AWS resource names.
service: debugme
plugins:
  - serverless-offline
provider:
  name: aws
  runtime: nodejs20.x

functions:
  hello:
    handler: handler.hello
    events:
      - httpApi:
          path: /
          method: get

• file: handler.js

"use strict"

const { stringify } = JSON

exports.hello = async function hello() {
  return {
    body: stringify({ foo: "bar" }),
    statusCode: 200,
  }
}

Expected behavior/code

The Node.js debugger should attach to the handler code when using the --inspect flag, allowing developers to step through the Lambda function code. The behavior described in the serverless-offline documentation should work without requiring workarounds.

Environment

• serverles version: v4.x.x
• serverless-offline version: v14.0.0
• node.js version: 20.16.0
• OS: NixOS

Possible Solution

I think serverless-offline should offer some flag that will run the handler code after opening the process to the inspector protocol. See https://nodejs.org/api/inspector.html#inspectoropenport-host-wait . I can't think of any other solution that would not involve changes on how serverless it self is run.

Additional context/Screenshots

The current documentation for serverless-offline is outdated and does not account for the changes introduced in v4. The Go binary acts as a wrapper that spawns additional child processes, which complicates the debugging process.

I did manage to get the debugger to attach, in an extremely hacky way, by calling the binary that serverless calls directly. See the attached images:

The following image (htop) demonstrates the hierarchy of processes, to better illustrate how this issue happens.

Here an image of htop when I ran the binary directly and successfully attached the debugger to it:

To be clear, this DOES NOT happen in v3, only in v4.

[jimmythomson]

I've just hit the same problem. Thanks for the work you've done to investigate this @danilevy1212 - this has allowed me to put in a workaround until I decide what to do going forwards. Unfortunately, with this issue and the login requirement in serverless v4 it's making me look for an alternative. It's such a shame as the serverless-offline team have done great work and the serverless-offline functionality works brilliantly for us.

[danilevy1212]

@jimmythomson Thank you, same here, I'm sticking with serverless v3 for the time being. Maybe with further adoption and more people hitting this issue, some official workaround will be made that the excellent developers of this repo can use.

[DorianMazur]

I have some ideas on how to fix this. I'll try to check it out soon.