Skip to content

Conversation

@skyrpex
Copy link

@skyrpex skyrpex commented Nov 14, 2025

Problem

The AWS SDK v2 to v3 migration in PR #8183 introduced breaking changes for LocalStack compatibility and Lambda debugging is not working anymore:

  1. User Agent format changed: The migration changed from string-based user agents to AWS SDK v3's UserAgent pairs format ([name, version] tuples), but several places still used the old string format, breaking LocalStack's custom user agent for Lambda debugging
  2. Response headers no longer accessible: AWS SDK v3 removed access to HTTP response headers via $response.httpResponse.headers, breaking LocalStack connection detection which relies on the x-localstack-request-url header

These issues were not caught most likely because LocalStack compatibility was not tested during the SDK v3 migration.

Solution

  1. Add response headers middleware for AWS SDK v3

    • Added captureHeadersMiddleware to AWSClientBuilderV3 that attaches HTTP response headers to the output via $httpHeaders property
    • Updated loginManager to check for LocalStack connection using $httpHeaders instead of the removed $response.httpResponse.headers
  2. Fix user agent format for AWS SDK v3

    • Migrated from string-based user agents to proper UserAgent pairs format:
      • Changed from "LAMBDA-DEBUG/1.0.0 AWS-Toolkit/..." (string)
      • To [['LAMBDA-DEBUG', '1.0.0'], ['AWS-Toolkit', '2.0'], ...] (pairs)
    • Updated awsClientBuilderV3 to use customUserAgent instead of userAgent

AWS SDK v3 Breaking Changes

User Agent Format

SDK v2:

// String format in client options
const options = {
    region: 'us-east-1',
    userAgent: 'LAMBDA-DEBUG/1.0.0 AWS-Toolkit/2.0.0'
}

SDK v3:

// Array of [name, version] tuples
const options = {
    region: 'us-east-1',
    customUserAgent: [
        ['LAMBDA-DEBUG', '1.0.0'],
        ['AWS-Toolkit', '2.0.0']
    ]
}

Response Headers Access

SDK v2:

const response = await client.send(command)
// Headers directly accessible
const headers = response.$response.httpResponse.headers
const localStackUrl = headers['x-localstack-request-url']

SDK v3:

const response = await client.send(command)
// Headers NOT accessible by default - requires custom middleware
const headers = response.$httpHeaders  // undefined without middleware

Supersedes #8289 as @carole-lavillonniere is OOO today and can't edit their PR.

@skyrpex skyrpex marked this pull request as ready for review November 14, 2025 12:27
@skyrpex skyrpex requested a review from a team as a code owner November 14, 2025 12:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants