serverless-offline "502 Internal Server Error" in CI

By Kaveh Alemi·Latchkey

serverless-offline maps a handler crash or a malformed Lambda proxy response to HTTP 502, mirroring API Gateway. The route reached your code, but the handler threw, returned the wrong shape, or never resolved.

What this error means

A request to a serverless-offline endpoint in CI returns "[502] Internal Server Error" and the offline log shows a handler exception or a malformed response payload.

Offline [http] error: [502] Internal Server Error
Error: Cannot read properties of undefined (reading 'id')
    at getUser (src/handlers/user.js:12:20)

Common causes

The handler threw an unhandled error

An exception in the handler (a bad property access, a failed downstream call) propagates, and offline returns 502.

A malformed Lambda proxy response

For lambda-proxy integration, the handler must return { statusCode, body }. Returning a bare object or a non-string body yields a 502.

How to fix it

Read the offline log and fix the throw

1. Look at the stack trace printed with the 502 in the offline log.
2. Handle the error or fix the input assumption in the handler.
3. Re-run the request.

Return a valid proxy response

Return the API Gateway proxy shape with a string body.

return {
  statusCode: 200,
  body: JSON.stringify({ ok: true }),
};

How to prevent it

• Return the correct { statusCode, body } proxy shape.
• Guard input access so missing fields do not throw.
• Cover handlers with offline integration tests in CI.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation