dherault / dherault/serverless-offline
Debugging Node.js with serverless-offline v4 Fails Due to Go Binary Interference
- Dominant language
- JavaScript
- Stars
- 5.3k
- Forks
- 811
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 3
Description
## 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`
```yaml
# "org" ensures this Service is used with the correct Serverless Framework Access Key.
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`
```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](https://www.serverless.com/plugins/serverless-offline#interactive-debugging-with-visual-studio-code-vsc) 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.
Contributor guide
Assessment
This issue has not been assessed yet.