Skip to content

[correlationId] Make correlationId a required parameter on AuthError constructors#8609

Merged
sameerag merged 2 commits into
devfrom
correlationId-in-errorpath
Jun 22, 2026
Merged

[correlationId] Make correlationId a required parameter on AuthError constructors#8609
sameerag merged 2 commits into
devfrom
correlationId-in-errorpath

Conversation

@sameerag

@sameerag sameerag commented May 27, 2026

Copy link
Copy Markdown
Member

Summary

** Makes correlationId a required parameter on the AuthError constructor (and all subclass error constructors) across every MSAL package. This ensures thrown errors carry correlation context consistently for telemetry and debugging.

Previously correlationId was attached after construction via setCorrelationId(), which was inconsistently called. That helper is removed; the value is now required at construction.

Scope of this PR

This PR now serves as the single consolidated PR for the correlationId error propagation work (instead of the original stacked split).

Beyond making the constructor parameter required, residual "" (placeholder) sites are being addressed per-component, starting with the lowest instance counts. For each component the throw sites are categorized into "real correlationId in scope → thread it" vs. "genuinely no request context → keep """ (e.g. interface/stub "not implemented" throws, static factory methods, pre-request config validation).

Changes

@azure/msal-common

  • AuthError constructor signature changed from (errorCode, errorMessage?, suberror?) to (errorCode, correlationId, errorMessage?, suberror?).
  • All subclasses updated: ClientAuthError, ClientConfigurationError, InteractionRequiredAuthError, ServerError, JoseHeaderError, NetworkError, CacheError.
  • setCorrelationId() removed.
  • Error helper signatures and call sites updated to pass correlationId (or "" where not yet in scope).
  • Where a real correlationId is already in scope, it is now passed instead of "" (e.g. Token.sendPostRequest network error fallback). Remaining "" sites are low-level utilities (e.g. ProtocolUtils, AuthToken) whose signatures don't yet carry correlationId; threading it through them is deferred follow-up.
  • API review file regenerated to reflect new public signatures.

@azure/msal-browser

  • Updated error construction paths to pass required correlationId.
  • Native auth error translation updated and test coverage expanded for correlationId propagation.
  • Pass the in-scope correlationId (instead of "") at PkceGenerator (generateCodeVerifier, generateCodeChallengeFromVerifier) and the BrowserUtils redirect-bridge empty-response path.

@azure/msal-react

  • ReactAuthError.createInvalidInteractionTypeError and createUnableToFallbackToInteractionError now accept an optional correlationId. useMsalAuthentication passes the in-scope value (loginRequest?.correlationId on the login path, the local correlationId on the acquireToken fallback path) instead of "".

@azure/msal-node-extensions

  • NativeBrokerPlugin.wrapError() now takes a correlationId, threaded from the request context at every call site, so the wrapped PlatformBrokerError, InteractionRequiredAuthError, ServerError, and createClient*Error branches all carry it. The signOut no-account throw now passes request.correlationId. The only remaining "" is the setLoggerRegisterLogger catch, which runs during logger registration with no request context.

@azure/msal-node

  • Error throw paths updated to pass required correlationId.
  • Threaded the in-scope correlationId (instead of "") through error paths where a real value was available:
    • NodeAuthError factory methods (createRedirectUriNotSupportedError, createNoAuthCodeInResponseError, createLoopbackServerTimeoutError, createStateNotFoundError) now accept an optional correlationId.
    • PublicClientApplication (acquireTokenInteractive/acquireTokenSilent, plus threading correlationId into the private waitForRedirectUri), ClientApplication.validateState, ConfidentialClientApplication (missingTenantIdError), ClientCredentialClient and OnBehalfOfClient cache throws (multipleMatchingTokens, tokenRefreshRequired), DeviceCodeClient (threaded into the private continuePolling and the unknown-error throw), and BaseManagedIdentitySource (network-error catch).
  • Remaining "" sites are pre-request config/input validation, boot-time managed-identity source selection/static factories, and interface/public-method signatures lacking a correlationId arg (INetworkModule/HttpClient, the managed-identity getServerTokenResponseAsync/getServerTokenResponse override chain, getManagedIdentityUserAssignedIdQueryParameterKey, ClientAssertion.getJwt); threading those requires wider shared/public signature changes and is tracked as continuing follow-up.

@azure/msal-angular

  • Mechanical fan-out: error throw paths updated to pass correlationId (or "" where not in scope). Both invalid_interaction_type throws (msal.guard.ts, msal.interceptor.ts) are pre-request configuration validation with no correlationId in scope, so they correctly remain "".
  • Threading real values into the remaining low-level/stub "" sites in the larger msal-common/msal-browser sets is tracked as continuing per-component follow-up.

Change files

  • Minor version bump change files included for affected packages.

Migration

// Before
throw new AuthError("my_code", "my message");
err.setCorrelationId(corrId);

// After
throw new AuthError("my_code", correlationId, "my message");

Copilot AI review requested due to automatic review settings May 27, 2026 06:55
@sameerag sameerag requested a review from a team as a code owner May 27, 2026 06:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR improves MSAL telemetry/debuggability by propagating the current request correlationId into errors created via msal-common/msal-browser error factory helpers, and updates internal throw sites and unit tests accordingly.

Changes:

  • Add optional correlationId parameters to several error creation helpers and forward correlationId at key throw sites.
  • Update native broker error translation (createNativeAuthError) to apply correlationId across translated error types.
  • Add/extend unit tests to verify correlationId behavior for updated helpers.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
lib/msal-common/test/error/InteractionRequiredAuthError.spec.ts Adds tests asserting correlationId behavior for interaction-required error factory.
lib/msal-common/test/error/ClientConfigurationError.spec.ts Adds tests asserting correlationId behavior for client configuration error factory.
lib/msal-common/test/error/ClientAuthError.spec.ts Adds tests asserting correlationId behavior for client auth error factory.
lib/msal-common/test/error/AuthError.spec.ts Adds tests asserting correlationId behavior for base auth error factory.
lib/msal-common/src/error/InteractionRequiredAuthError.ts Extends interaction-required error factory signature to accept correlationId.
lib/msal-common/src/error/ClientConfigurationError.ts Extends configuration error factory signature to accept/set correlationId.
lib/msal-common/src/error/ClientAuthError.ts Extends client auth error factory signature to accept/set correlationId.
lib/msal-common/src/error/AuthError.ts Extends base auth error factory signature to accept/set correlationId.
lib/msal-common/src/client/SilentFlowClient.ts Forwards request.correlationId when throwing client auth errors.
lib/msal-common/src/client/RefreshTokenClient.ts Forwards request.correlationId when throwing interaction-required errors.
lib/msal-common/src/client/AuthorizationCodeClient.ts Forwards request.correlationId when throwing client/configuration errors.
lib/msal-browser/test/error/NativeAuthError.spec.ts Adds tests asserting correlationId is preserved on translated native errors.
lib/msal-browser/test/error/BrowserConfigurationAuthError.spec.ts Adds tests asserting correlationId behavior for browser configuration error factory.
lib/msal-browser/test/error/BrowserAuthError.spec.ts Adds tests asserting correlationId behavior for browser auth error factory.
lib/msal-browser/src/interaction_client/SilentAuthCodeClient.ts Forwards correlationId into thrown browser auth errors.
lib/msal-browser/src/interaction_client/PopupClient.ts Forwards correlationId into thrown browser auth errors in popup flows.
lib/msal-browser/src/interaction_client/PlatformAuthInteractionClient.ts Forwards correlationId into thrown common/browser errors in platform auth flows.
lib/msal-browser/src/interaction_client/BaseInteractionClient.ts Forwards correlationId into thrown common configuration errors.
lib/msal-browser/src/error/NativeAuthError.ts Extends native error translation to accept/apply correlationId.
lib/msal-browser/src/error/BrowserConfigurationAuthError.ts Extends browser configuration error factory to accept/set correlationId.
lib/msal-browser/src/error/BrowserAuthError.ts Extends browser auth error factory to accept/set correlationId.
lib/msal-browser/src/controllers/StandardController.ts Forwards correlationId into thrown common/browser errors in controller paths.
lib/msal-browser/src/broker/nativeBroker/PlatformAuthExtensionHandler.ts Forwards correlationId when translating/throwing native and auth errors.
lib/msal-browser/src/broker/nativeBroker/PlatformAuthDOMHandler.ts Forwards correlationId when translating/throwing native and auth errors.
change/@azure-msal-common-151e2ba1-220e-4a47-a4dc-e421d262da2a.json Adds patch changefile for msal-common.
change/@azure-msal-browser-7c559b7a-066d-486b-b68f-4b4359e3f053.json Adds patch changefile for msal-browser.

Comment thread lib/msal-common/src/error/AuthError.ts
Comment thread lib/msal-common/src/error/InteractionRequiredAuthError.ts
Comment thread lib/msal-browser/src/error/NativeAuthError.ts
Comment thread change/@azure-msal-common-151e2ba1-220e-4a47-a4dc-e421d262da2a.json Outdated
Comment thread change/@azure-msal-browser-7c559b7a-066d-486b-b68f-4b4359e3f053.json Outdated
Comment thread lib/msal-browser/test/error/NativeAuthError.spec.ts
Comment thread lib/msal-common/src/error/AuthError.ts Outdated
@sameerag sameerag force-pushed the correlationId-in-errorpath branch from b372320 to 098cb6e Compare May 28, 2026 21:59
@sameerag sameerag changed the title Propagate correlationId through error creation helpers Make correlationId a required parameter on AuthError constructors (breaking) May 28, 2026
@sameerag sameerag changed the title Make correlationId a required parameter on AuthError constructors (breaking) [correlationId 1/4] Make correlationId a required parameter on AuthError constructors (breaking) May 29, 2026
@sameerag

Copy link
Copy Markdown
Member Author

@copilot Let us get to a restoration Point. Do you recall the 4 PRs reated as a part of the correlationId addition to errors?

Copilot AI commented May 30, 2026

Copy link
Copy Markdown
Contributor

@copilot Let us get to a restoration Point. Do you recall the 4 PRs reated as a part of the correlationId addition to errors?

From the current PR context I can reliably identify these stacked items:

  1. [correlationId 1/4] required correlationId on AuthError constructors (this PR)
  2. [correlationId 2/4] thread correlationId through internal msal-common helpers
  3. [correlationId 3/4] createAccessTokenEntity + createAccountEntity API break

I don’t have a confirmed 4th PR identifier in the thread metadata here. If you share the 4th PR number/title, I can align to the exact restoration point you want.

@sameerag

Copy link
Copy Markdown
Member Author

@copilot *created

Copilot AI commented May 30, 2026

Copy link
Copy Markdown
Contributor

@copilot *created

Yes — the 4 created PRs are:

@sameerag

Copy link
Copy Markdown
Member Author

@copilot Is the format fixed?

Comment thread change/@azure-msal-angular-correlationid-required-8609.json Outdated
Comment thread change/@azure-msal-browser-7c559b7a-066d-486b-b68f-4b4359e3f053.json Outdated
Comment thread change/@azure-msal-common-151e2ba1-220e-4a47-a4dc-e421d262da2a.json Outdated
Comment thread change/@azure-msal-node-correlationid-required-8609.json Outdated
Comment thread change/@azure-msal-node-extensions-correlationid-required-8609.json Outdated
Comment thread change/@azure-msal-react-correlationid-required-8609.json Outdated
tnorling
tnorling previously approved these changes Jun 11, 2026
@sameerag

Copy link
Copy Markdown
Member Author

@copilot Push api extractor changes

Copilot AI commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

@copilot Push api extractor changes

Regenerated and pushed the API extractor reports. Only lib/msal-browser/apiReview/msal-browser.api.md had changes — it now reflects the required correlationId parameter on the NativeAuthError/BrowserAuthError constructors and the getHomepage(correlationId?) signature. The msal-common, msal-node, and msal-react reports were already in sync (apiExtractor completed with no diff).

@sameerag

Copy link
Copy Markdown
Member Author

@copilot Push api extractor changes

Copilot AI commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

@copilot Push api extractor changes

The API extractor changes are already pushed — the msal-browser apiReview update is in commit 106fd72. I rebuilt and re-ran apiExtractor for all four lib packages (msal-common, msal-browser, msal-node, msal-react) and every one now completes successfully with no diff, so the working tree is clean and there's nothing further to push.

@sameerag

Copy link
Copy Markdown
Member Author

@copilot Pipelines are failing with 1P compat. Can you try debug?

Copilot AI commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

@copilot Pipelines are failing with 1P compat. Can you try debug?

Debugged it. The failure is expected breakage in the 1P consumer, not a regression in this repo.

What's failing: The "MSAL JS Build" / 1P compat job (​.pipelines/1p-build.yml, 1p-e2e.yml) builds the internal msal-browser-1p package — pulled from IDDP/msal-javascript-1p (ref: dev) — against this branch's msal-common/msal-browser. This PR makes breaking changes to the public/internal API surface that msal-browser-1p consumes, so its TypeScript compile fails:

  • correlationId is now a required parameter on AuthError and every subclass constructor (ClientAuthError, ClientConfigurationError, InteractionRequiredAuthError, ServerError, etc.) and on many create*Error factories/utilities (createAuthError, createClientAuthError, createInteractionRequiredAuthError, …).
  • AuthError.setCorrelationId() was removed — any 1P code calling err.setCorrelationId(corrId) no longer compiles (hard break, not just a positional shift).

This repo is clean: all 4 lib packages build, apiExtractor is in sync for each (no diff), and lint/format pass after the latest dev merge. So there's nothing to fix on the JS side — the break is purely in the inaccessible internal repo.

To get 1P compat green, a companion change is needed in IDDP/msal-javascript-1p (msal-browser-1p) to:

  1. Pass correlationId to the error constructors/factories it calls, and
  2. Replace setCorrelationId() calls with the assignable error.correlationId field.

I don't have access to that internal repo, so I can't push that change from here. If you can point me at it (or want to keep this fully backward-compatible instead), the alternative is to keep setCorrelationId() and make the constructor correlationId optional/appended-last — but that would undo the "required" intent of this PR. Let me know which direction you'd like.

@sameerag sameerag force-pushed the correlationId-in-errorpath branch from 8723b13 to 605aaaa Compare June 19, 2026 02:53
…constructors

Squash-rebased onto dev. Threads a required correlationId through error
constructors and creation helpers across msal-common, msal-browser,
msal-node, msal-react, msal-angular, and msal-node-extensions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@sameerag sameerag force-pushed the correlationId-in-errorpath branch from 605aaaa to c4835e8 Compare June 19, 2026 05:44
@sameerag sameerag enabled auto-merge (squash) June 19, 2026 18:42
@sameerag sameerag merged commit 27c074b into dev Jun 22, 2026
73 checks passed
@sameerag sameerag deleted the correlationId-in-errorpath branch June 22, 2026 11:48
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.

5 participants