Debugging-Lambda-API-GW.md

Debugging Serverless Lambda 500 Errors

1. Verify Basic Deployment and Connectivity

• Confirm Endpoints: After serverless deploy, run serverless info to list endpoints and stack outputs. Ensure the URLs match exactly, including the stage (e.g., /dev/).
• Test with Tools: Use curl -v https://your-endpoint.com/path or Postman to inspect response headers for clues (e.g., CORS or "Internal Server Error").
• AWS Console Check: Navigate to API Gateway > Your API > Stages and verify no deployment errors or invalid mappings.

2. Inspect Lambda Logs via CloudWatch

This is often the fastest way to identify errors, as 500s typically log stack traces.

• Enable Logging: In serverless.yml, ensure provider: logs: rest: true for API Gateway.
• AWS Console: Go to CloudWatch > Log groups > /aws/lambda/your-function-name. Filter recent invocations for errors like unhandled exceptions, timeouts, or missing modules.
• CLI: Run serverless logs -f yourFunctionName --tail to stream logs while hitting the endpoint.
• Common Issues: Runtime errors (e.g., undefined variables), missing environment variables, or dependency issues (verify package.json/requirements are bundled).

3. Test Lambda Function in Isolation

Bypass API Gateway to isolate the issue.

• AWS Console: Lambda > Functions > Your function > Test tab. Create a test event mimicking the API request (e.g., JSON with method, path, headers).
• Outcome: If it fails, suspect code/config; if it succeeds, check API Gateway (e.g., integration mappings or authorization).
• CLI: Use serverless invoke -f yourFunctionName --data '{"key": "value"}' to simulate.

4. Check Permissions and IAM Roles

500s can result from Lambda lacking resource access (e.g., DynamoDB, S3).

• Serverless Config: Ensure provider.iamRoleStatements in serverless.yml grants necessary permissions.
• AWS Console: Lambda > Your function > Configuration > Permissions. Verify the execution role and test policies with IAM Policy Simulator if needed.
• Log Check: Look for "AccessDeniedException" in CloudWatch.

5. Review Configuration and Dependencies

• Validate Config: Check serverless.yml for correct function handlers, environment variables, and plugins (e.g., serverless-offline). Run serverless print to expand config.
• Dependencies: For Node.js/Python, ensure all dependencies are included (use serverless package to inspect the zip). Watch for native modules not built for Lambda runtime.
• Environment Variables: Missing secrets/configs cause runtime failures—use AWS SSM or Secrets Manager and reference correctly.

6. Enable Advanced Tracing (If Needed)

• X-Ray: Add provider: tracing: lambda: true in serverless.yml. Use AWS X-Ray to trace invocations and analyze init vs. invocation time.
• API Gateway Logging: Enable execution logs in API Gateway stages for request/response details.
• Timeouts: If suspected, check/increase Lambda timeout/memory in serverless.yml.

Logging and Tracking example

provider:
  name: aws
  runtime: nodejs18.x  # Adjust to your runtime
  stage: ${opt:stage, 'dev'}
  region: us-east-1

  # Logging
  logs:
    lambda:
      logFormat: json
      logRetentionInDays: 30
    restApi:
      executionLogging: true
      level: INFO
      fullExecutionData: true
      accessLogging: true

  # Tracing
  tracing:
    lambda: true
    apiGateway: true

  # IAM for X-Ray (if needed)
  iamRoleStatements:
    - Effect: Allow
      Action:
        - xray:PutTraceSegments
        - xray:PutTelemetryRecords
      Resource: "*"

functions:
  yourFunction:
    handler: handler.main
    events:
      - http:
          path: /your-path
          method: get