dherault / dherault/serverless-offline

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

Open
#1,810 6 comments 3 reactions 0 assignees View on GitHub
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:

![image](https://github.com/user-attachments/assets/0726ac0d-b451-44a8-b8f6-ad9046557c1f)
![image](https://github.com/user-attachments/assets/b4f8c194-d961-42c2-b1f4-89761bb0fc09)

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

image

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

![image](https://github.com/user-attachments/assets/132cdadf-0712-4695-bb3e-7ce30941c798)

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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.