[tonytrinh3]

Summary

Read this first: this PR only changes error text. It fixes no load failure. It adds no feature. It does not fix the original AIC-3370 crash, because that crash happened before any SDK code ran. PR #77 fixed that part.

|
|
|
||
||
||
||
||
||
||
||
|

Plain version: The SDK loads a few optional packages while it starts. A bundler can break that load. The old error message said the package is missing. That message was wrong, because the package is installed. The import still fails. The message now states the real cause and the fix.

What it means for the code (junior eng): packages/client/src/lifecycle.ts loads optional packages with await import(). A bundler can turn that call into require(). require() cannot load an ESM-only package. ESM means ECMAScript Modules, the import/export module format. Node then throws ERR_REQUIRE_ESM or a similar error. Both catch blocks used to report "not installed" for every error. Now a classifier reads the error first.

Closes AIC-3416. This PR is part of AIC-3370. This PR is stacked on #77 (AIC-3415).

• The new file packages/client/src/import-diagnostics.ts sorts a failed import into three groups. The groups are ESM interoperability, a missing package, and an unknown error.
• The ESM message names the package. It contains the phrase ESM package was externalized into CommonJS output. It gives the fix allowlist: [/^@launchdarkly\/ai-/]. It links the Lambda recipe in packages/ai-node/README.md.
• Every new error keeps the original error in cause.
• An unknown error passes through without a new label. Before this PR, the SDK called every failure "not installed".
• The telemetry path warns one time per process. shutdownTelemetry() resets that state. The node SDK path still throws.

Which AIC-3370 asks this PR answers

Plain version: This PR answers ask 5 only. Ask 5 wants an error message that names the real cause. The message names the package. It says the bundler externalized an ESM package. It gives the fix. It links the Lambda recipe. It keeps the original error, so no detail is lost.

What it means for the code (junior eng): esmExternalizationDiagnostic in packages/client/src/import-diagnostics.ts builds the text. The text contains ESM package was externalized into CommonJS output. It contains allowlist: [/^@launchdarkly\/ai-/]. It links the recipe in packages/ai-node/README.md. describeImportFailure sets cause to the original error. packages/client/src/__tests__/import-diagnostics.test.ts covers the codes, the message forms, a real MODULE_NOT_FOUND, an unknown error, the preserved cause, and the warn-once behavior.

The limit matters. The diagnostic covers the optional dynamic imports in packages/client/src/lifecycle.ts. Those imports run after #77 fixes root package resolution. The diagnostic cannot catch the original root import failure. That failure happens in the Node resolver, before our code runs.

This PR answers no other ask. Ask 1 is #77. Ask 2 is #76. Ask 4 is #76. Ask 3 is #76 plus #79.

Implementation details

The old behavior

Both optional imports discarded the error:

// setupTelemetry
} catch { console.warn('...OpenTelemetry SDK packages are not installed...'); return; }

// initBaseClient
} catch { throw new Error('...node-server-sdk is not installed...'); }

Both messages are wrong when the package is present. The bundler is the real cause.

The new behavior

// setupTelemetry
} catch (err) {
  if (isEsmInteropError(err)) {
    warnEsmExternalizationOnce(moduleNameFromError(err, 'an OpenTelemetry SDK package'), err);
    return;
  }
  // the peer dependency install message stays the same
}

// initBaseClient
} catch (err) {
  throw describeImportFailure('@launchdarkly/node-server-sdk', err, MISSING_NODE_SDK_MESSAGE);
}

describeImportFailure(moduleName, error, missingDependencyMessage) returns one of three values. It returns the ESM message with cause. It returns the install message with cause. It returns the original error object.

How the classifier decides

The classifier reads the error code first. It treats ERR_REQUIRE_ESM and ERR_PACKAGE_PATH_NOT_EXPORTED as ESM interoperability errors. It treats MODULE_NOT_FOUND and ERR_MODULE_NOT_FOUND as a missing package.

The classifier then reads the message text. A bundled loader does not always keep the code property. The message patterns are require() of ES Module, Must use import to load ES Module, No "exports" main defined, is not defined by "exports", and Cannot find module/package.

moduleNameFromError reads the package name from the quoted specifier. It also reads the name from a node_modules/<pkg> path. The caller passes a fallback name, so the message never shows an empty name.

Scope limit

This PR does not catch the original failure from before PR2. That failure happened in the package resolver, before any SDK code ran. PR #77 removed that failure.

One behavior change to review

The node SDK path used to report "not installed" for every failure. An unrelated failure now propagates unchanged. An example is a TypeError from inside the package itself.

Alternatives that I rejected

I did not export the classifier from the public barrel. The diagnostic is internal.

I did not keep the logic inside lifecycle.ts. A separate file is easier to test. Vitest replaces a throwing import mock with its own factory error. That made the lifecycle tests flaky.

Testing

packages/client/src/__tests__/import-diagnostics.test.ts covers each error code and each message form. It checks that a real MODULE_NOT_FOUND keeps the install message. It checks that an unknown error passes through by identity. It checks a non-error throw. It checks cause. It checks module name extraction from a specifier, from a path, and from the fallback. It checks the message content. It checks the warn-once behavior and the reset.

I ran these commands from the repo root, and all passed: yarn build, yarn typecheck, yarn code:check, yarn lint:pkg, yarn test (395 client tests, three runs to check for flakes), and yarn test:integration (21 tests from the PR1 harness).

This PR changes no UI. There is no staging preview.

Reviewer guide

1. Read packages/client/src/import-diagnostics.ts first. It holds the classifier and the message text.
2. Read the two catch blocks in packages/client/src/lifecycle.ts. The telemetry path still warns and continues. The node SDK path still throws.
3. Read packages/client/src/__tests__/import-diagnostics.test.ts.

Link to Devin session: https://app.devin.ai/sessions/d378cea89d3841e19600978ae3c8f2ad
Open in Devin Desktop: https://app.devin.ai/desktop/session/d378cea89d3841e19600978ae3c8f2ad?variant=devin
Requested by: @tonytrinh3

---

Note

Overview
Improves error messaging only when optional await import() calls in client initialization fail because a bundler externalized ESM packages into CommonJS (misleading “not installed” text before).

Adds import-diagnostics to classify failures: ESM interop (ERR_REQUIRE_ESM, message patterns), genuine missing modules, or pass-through for unrelated errors. ESM cases get a diagnostic naming the package, an allowlist: [/^@launchdarkly\/ai-/] hint, and a link to the Lambda/Webpack recipe; wrapped errors keep the original in cause.

lifecycle.ts now uses this in the OpenTelemetry setup catch (one-time console.warn via warnEsmExternalizationOnce, reset on shutdownTelemetry) and in the @launchdarkly/node-server-sdk import catch (describeImportFailure still throws, but with the right message). True MODULE_NOT_FOUND still shows install guidance; other failures are no longer mislabeled as missing deps.

Vitest coverage in import-diagnostics.test.ts exercises classification, module name extraction, diagnostics, and warn-once behavior.

^{Reviewed by Cursor Bugbot for commit dc16a78. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

@cursor review

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f90b97a. Configure here.}