Hey Lukas, let’s dig into why your generate function works locally with sls invoke local but throws a 502 Bad Gateway when run remotely. This is super common with headless Chrome in serverless environments like AWS Lambda, and it almost always ties to Chromeless configuration or environment mismatches. Here are the top issues to check:

1. Missing or Misconfigured Chrome Binary Path #

Your local machine has Chrome installed, but Lambda’s default execution environment doesn’t. If you’re using Chromeless, you need to ensure it can access a Lambda-compatible Chrome binary—most folks use a pre-built layer like serverless-chrome or package the binary themselves.

• Double-check your Chromeless config has an explicit chromePath pointing to the correct location. For Lambda layers, this is usually /opt/chrome/chrome.
• Without this setting, Chromeless will try to call the system’s Chrome executable, which doesn’t exist in Lambda, causing the function to crash silently and return a 502.

2. Insufficient Memory or Timeout Limits #

Headless Chrome is resource-heavy—Lambda’s default 128MB of memory is way too low. Even simple PDF generation can choke on that.

• Update your serverless.yml to set memorySize to at least 512MB (1024MB is better for complex PDFs) and timeout to 30+ seconds. Example:

  functions:
    generate:
      handler: pdf.generate
      memorySize: 1024
      timeout: 30
      # other config...
  

• If the function runs out of memory or times out, Lambda will terminate it abruptly, resulting in a 502.

3. Missing Critical Chrome Flags for Serverless #

Chrome needs specific flags to run in Lambda’s restricted environment. The most commonly missing ones are:

import { Chromeless } from 'chromeless';

const chromeless = new Chromeless({
  chromeFlags: [
    '--headless',
    '--disable-gpu',
    '--no-sandbox', // Critical—Lambda doesn't support Chrome's sandbox
    '--disable-dev-shm-usage', // Fixes "/dev/shm" space limits in Lambda
    '--single-process', // Reduces resource overhead
    '--disable-setuid-sandbox', // Additional sandbox disable flag
  ],
  // Ensure remote is set to false (we're running Chrome locally in the function)
  remote: false,
});

• Omitting --no-sandbox is the #1 culprit here—Chrome will fail to start entirely without it in Lambda.

4. Dependency Packaging Incompatibility #

If you installed npm packages like chromeless on macOS/Windows, their bundled binaries won’t work on Lambda’s Linux environment.

• Use Docker to simulate Lambda’s Linux environment when installing dependencies, or use tools like serverless-webpack to bundle your code with Linux-compatible binaries.
• Avoid zipping your local node_modules directly—this often includes platform-specific files that break in Lambda.

5. Network or VPC Restrictions #

If your PDF is generated from an internal URL or requires access to private resources, your Lambda function might not have the right network access:

• If you’re using a VPC, ensure your function is attached to subnets with internet access (or a NAT gateway) if it needs to fetch external pages.
• Check security groups to make sure outbound traffic is allowed to the resources your PDF relies on.

Next Step: Check CloudWatch Logs #

Before tweaking more settings, pull up your Lambda function’s CloudWatch logs. The 502 is a generic gateway error, but the logs will show the actual root cause—whether it’s a Chrome startup failure, memory issue, or missing dependency. This will save you a ton of guesswork.

内容的提问来源于stack exchange，提问作者Lukas Holzer