Bug: `AWS_SDK_UA_APP_ID` can exceed 50-character limit during initialisation

[akee01]

Expected Behavior

The AWS_SDK_UA_APP_ID should remain within the 50-character limit and should not contain redundant or duplicated Powertools version strings, ensuring compatibility with the AWS SDK.

Why this matters

As shown in the logic flow of how User Agents are constructed, the App ID is a suffix that helps AWS identify the origin of the request. If it is malformed or too long, it risks breaking the integration with AWS services that enforce strict header validation.

Current Behavior

In packages/commons/src/index.ts, the logic used to append Powertools metadata to the AWS_SDK_UA_APP_ID environment variable does not account for the AWS SDK's 50-character limit or the possibility of multiple initializations (e.g., when multiple versions of commons exist in the dependency tree).

The current implementation blindly appends strings:

if (process.env.AWS_SDK_UA_APP_ID) {
  process.env.AWS_SDK_UA_APP_ID = `${process.env.AWS_SDK_UA_APP_ID}/PT/NO-OP/${PT_VERSION}/PTEnv/${env}`;
} else {
  process.env.AWS_SDK_UA_APP_ID = `PT/NO-OP/${PT_VERSION}/PTEnv/${env}`;
}

If a user already has an App ID defined, or if two different versions of the library are loaded (common in monorepos or nested dependencies), the string can quickly look like this:
MyCustomAppID/PT/NO-OP/2.0.0/PTEnv/prod/PT/NO-OP/2.1.0/PTEnv/prod

This exceeds the 50-character limit defined in the AWS SDK Shared Configuration documentation, which may lead to SDK initialization errors or truncated User-Agent headers.

Code snippet

/**
 * Reproduction Script: AWS SDK UA App ID Overflow
 * This simulates how 'packages/commons/src/index.ts' handles the environment variable.
 */

const PT_VERSION = "2.0.4";
const env = "production";
const LIMIT = 50;

function simulateCommonsInit() {
    // This is the exact logic currently in Powertools commons
    if (process.env.AWS_SDK_UA_APP_ID) {
        process.env.AWS_SDK_UA_APP_ID = `${process.env.AWS_SDK_UA_APP_ID}/PT/NO-OP/${PT_VERSION}/PTEnv/${env}`;
    } else {
        process.env.AWS_SDK_UA_APP_ID = `PT/NO-OP/${PT_VERSION}/PTEnv/${env}`;
    }
}

// --- SCENARIO 1: User already has a custom App ID ---
process.env.AWS_SDK_UA_APP_ID = "MyCompany-ECommerce-Ordering-Service"; // 36 chars
console.log(`Initial Length: ${process.env.AWS_SDK_UA_APP_ID.length}`);

simulateCommonsInit();

console.log(`\n--- After 1st Init ---`);
console.log(`Value:  ${process.env.AWS_SDK_UA_APP_ID}`);
console.log(`Length: ${process.env.AWS_SDK_UA_APP_ID.length}`);
console.log(`Status: ${process.env.AWS_SDK_UA_APP_ID.length > LIMIT ? '❌ FAILED (Too Long)' : '✅ OK'}`);

// --- SCENARIO 2: Multiple versions of Powertools loaded ---
// (Simulating a second 'commons' package from a different version/location being loaded)
simulateCommonsInit();

console.log(`\n--- After 2nd Init (Multiple Versions) ---`);
console.log(`Value:  ${process.env.AWS_SDK_UA_APP_ID}`);
console.log(`Length: ${process.env.AWS_SDK_UA_APP_ID.length}`);
console.log(`Status: ${process.env.AWS_SDK_UA_APP_ID.length > LIMIT ? '❌ FAILED (Too Long)' : '✅ OK'}`);

Steps to Reproduce

1. Set an initial environment variable: export AWS_SDK_UA_APP_ID="MyExistingApplicationID" (24 chars)
2. Import any Powertools utility that triggers the commons index initialization
3. Observe that the new value is ~55+ characters
4. If a second version of commons is initialised, the string grows indefinitely

Possible Solution

1. Idempotency: Check if the string already contains PT/NO-OP before appending
2. Bounds Checking: Ensure the final string is sliced to a maximum of 50 characters

Powertools for AWS Lambda (TypeScript) version

latest

AWS Lambda function runtime

24.x

Packaging format used

npm

Execution logs

WARN The provided userAgentAppId exceeds the maximum length of 50 characters.

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #typescript channel on our Powertools for AWS Lambda Discord: Invite link

[gorets]

For a long time, I also couldn't figure out where this additional log was coming from. Nothing like this happened when using v 2.18.0.

[dreamorosi]

Hi both - sorry for the late response.

Rather than a synthetic code snippet like the one above, could you please provide a minimal reproducible example of this happening?

We are aware that the logic as it's written is not idempotent, however this is potentially a symptom of a larger issue in your codebase, which is multiple copies of the same module being loaded - which has a negative impact on cold start, performance, and overall cost of your function.

[gorets]

Title: AWS_SDK_UA_APP_ID doubled when CJS and ESM versions of @aws-lambda-powertools/commons are both loaded, causing AWS SDK userAgentAppId warning

---

Description

When a Lambda function uses @aws-lambda-powertools alongside a dependency that is a CJS package and internally requires @aws-lambda-powertools/logger (or
any other powertools package), the module-level initialization code in @aws-lambda-powertools/commons runs twice — once for the ESM version and once for
the CJS version. This causes AWS_SDK_UA_APP_ID to grow beyond 50 characters, triggering a warning from the AWS SDK v3:

WARN The provided userAgentAppId exceeds the maximum length of 50 characters.

---

Root cause

@aws-lambda-powertools/commons/lib/esm/index.js and @aws-lambda-powertools/commons/lib/cjs/index.js both contain the following module-level initialization:

const env = process.env.AWS_EXECUTION_ENV || 'NA';
if (process.env.AWS_SDK_UA_APP_ID) {
process.env.AWS_SDK_UA_APP_ID = ${process.env.AWS_SDK_UA_APP_ID}/PT/NO-OP/${PT_VERSION}/PTEnv/${env};
} else {
process.env.AWS_SDK_UA_APP_ID = PT/NO-OP/${PT_VERSION}/PTEnv/${env};
}

In Node.js, the ESM and CJS versions of the same package are treated as separate modules with separate file paths (lib/esm/index.js vs lib/cjs/index.js).
They do not share the module cache. If both are loaded in the same process, the initialization block runs twice, each time appending to AWS_SDK_UA_APP_ID.

---

Reproduction scenario

1. Lambda function (type: module / ESM format) imports powertools directly:
   import { Metrics } from '@aws-lambda-powertools/metrics'; // ESM → loads commons ESM
   import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware'; // ESM → commons already cached (ESM)
2. The same function also imports a CJS package that internally does:
   const logger = require('@aws-lambda-powertools/logger'); // CJS → loads commons CJS
3. Node.js loads commons/lib/esm/index.js for step 1 and commons/lib/cjs/index.js for step 2. Both run their initialization block against the same
   process.env.AWS_SDK_UA_APP_ID.

Result after both loads (with AWS_EXECUTION_ENV=AWS_Lambda_nodejs22.x, version 2.32.0):

PT/NO-OP/2.32.0/PTEnv/AWS_Lambda_nodejs22.x/PT/NO-OP/2.32.0/PTEnv/AWS_Lambda_nodejs22.x
87 characters — exceeds the 50-character AWS SDK limit.

---

Why the warning surfaces only on specific middleware

The AWS SDK v3 validates userAgentAppId inside resolveUserAgentConfig at the moment an SDK client is instantiated. If the first eagerly-created client
(e.g., AppConfigClient in a middleware initialized at module load time) is instantiated after both CJS and ESM versions of commons have run, the warning
fires. Lazily-created clients (e.g., CloudWatchClient inside Powertools Metrics, created only on first publishStoredMetrics() call) also trigger this
warning but do so inside the request handler, where it may be less noticeable or attributed to a different cause.

---

Expected behavior

AWS_SDK_UA_APP_ID should be appended to only once per process, regardless of whether commons is loaded via CJS or ESM.

---

Suggested fix

Deduplicate the initialization by checking whether the Powertools marker is already present before appending:

const marker = PT/NO-OP/${PT_VERSION}/PTEnv/${env};
if (!process.env.AWS_SDK_UA_APP_ID?.includes('PT/NO-OP/')) {
process.env.AWS_SDK_UA_APP_ID = process.env.AWS_SDK_UA_APP_ID
? ${process.env.AWS_SDK_UA_APP_ID}/${marker}
: marker;
}

Or, more robustly, truncate the final value to 50 characters before writing it.

---

Environment

• @aws-lambda-powertools/*: 2.32.0
• @aws-sdk/client-appconfig: (any v3)
• Node.js runtime: nodejs22.x
• Lambda format: ESM (type: module)

[dreamorosi]

While we ship both CJS & ESM versions in the same npm packages, your code/application should be loading only one of the two.

If both are being loaded, there seems to be some issue with your bundle and/or how you're loading Powertools.

[gorets]

While we ship both CJS & ESM versions in the same npm packages, your code/application should be loading only one of the two.

If both are being loaded, there seems to be some issue with your bundle and/or how you're loading Powertools.

In my case, I had a rather specific situation using a middi5-based stack, which has an ESM-only support.

I created a separate package for this stack, expanding the functionality of PowertoolLogger, and it's designed for ESM.

However, the project also includes PowertoolMetrics, and it seems each package pulls in its own version of the PowertoolCommon library, which leads to double-entry into environment variables.

[dreamorosi]

However, the project also includes PowertoolMetrics, and it seems each package pulls in its own version of the PowertoolCommon library, which leads to double-entry into environment variables.

Again - that seems to be either a version mismatch or a ESM/CJS conflict, this shouldn't be happening.

Can you please try creating a self-contained reproducible example of this happening, so we can look at it?