If you've ever encountered the frustrating ECONNREFUSED error while working with Serverless Offline, you're not alone. I was getting this error when I tried to run e2e tests with cypress. The frontend was working fine and was able to hit the serverless offline backend but in cypress tests, it was giving refused connection errors. In this blog, I'll walk you through how I solved this problem and got my serverless backend up and running locally.

The Problem

While running my e2e cypress tests locally, I kept running into the following error:

Error: connect ECONNREFUSED 127.0.0.1:8080

This error indicated that my application (or Cypress tests) couldn't connect to the backend running on localhost:8080. Surprisingly, the backend worked fine when tested manually with curl or Postman or browser, but it failed when accessed via Cypress or other tools.

The Solution

After some debugging, I discovered two key changes that resolved the issue:

1. Change the Port

By default, sls offline runs on port 8080. However, this port might already be in use by another process on your machine. To fix this, I updated the serverless.yml file to use a different port (e.g., 8000):

custom:
  serverless-offline:
    httpPort: 8000

2. Set the Host Explicitly

Sometimes, sls offline binds to localhost by default, which can cause issues in certain environments. To ensure the server is accessible from all network interfaces, I explicitly set the host to 0.0.0.0:

custom:
  serverless-offline:
    httpPort: 8000
    host: 0.0.0.0

After making these changes, I restarted sls offline, and there you go! The backend was now accessible at http://localhost:8000.

Why This Works

• Changing the Port: If port 8080 is already in use, switching to a different port (e.g., 8000) ensures there’s no conflict.
• Setting the Host to 0.0.0.0: Binding to 0.0.0.0 makes the server accessible from any network interface, not just localhost. This is especially useful when working with tools like Cypress or Docker.

Steps to Reproduce the Fix

1. Update your serverless.yml file:

   custom:
     serverless-offline:
       httpPort: 8000
       host: 0.0.0.0

1. Restart sls offline:

   sls offline

1. Test the backend using curl or your application:

   curl -X POST http://localhost:8000/prod/signIn \
     -H "Content-Type: application/json" \
     -d '{"email": "test@example.com", "password": "your-password"}'

You can also resolve the issue via terminal command by running sls offline with specific options directly. This can be done in one line like so:

sls offline start --httpPort 8000 --host 0.0.0.0

This command will start your serverless offline environment on port 8000 and bind it to 0.0.0.0, making the backend accessible from all network interfaces without the need to modify the serverless.yml file manually. It's a quick and efficient alternative for testing.

Bonus Tip: Debugging with Cypress

If you're using Cypress for end-to-end testing and still encountering issues, try hitting the backend directly:

cy.request({
        method: 'POST',
        url: 'http://localhost:8000/api/signIn', // Replace with your backend URL
        body: {
          email: Cypress.env("TEST_USER_EMAIL"),
          password: Cypress.env("TEST_USER_PASSWORD"),
        },
      }).then((response) => {
        expect(response.status).to.equal(200);
        expect(response.body.token).to.exist;
      });