DIAG: instrument userButton mount path (do not merge) by jacekradko · Pull Request #8436 · clerk/javascript

jacekradko · 2026-04-30T18:49:55Z

Do not merge. Diagnostic patch to capture exactly what state `useUserBase` and `withCoreUserGuard` see at the moment the userButton fails to paint.

Adds three `[CLERK_DIAG]` console.log lines:

`packages/clerk-js/src/core/clerk.ts` `#emit` — every emit, with the user/session/client ids it carries
`packages/shared/src/react/hooks/base/useUserBase.ts` `getSnapshot` — every snapshot read, with whether it fell back to initial state and what it returned
`packages/ui/src/contexts/CoreUserContext.tsx` `withCoreUserGuard` — every render, with whether the guard passed the user through or returned null

When the express/hono userButton tests fail, the playwright trace now contains the diagnostic logs and we can definitively see whether the issue is:

(a) clerk-js never emits with a user resource (server response shape problem),
(b) clerk-js emits but `__internal_lastEmittedResources` is somehow not what useSyncExternalStore reads,
(c) the snapshot returns a user but withCoreUserGuard still hits the null branch (closure/stale-state).

Will be closed after we read the next CI run's traces.

changeset-bot · 2026-04-30T18:50:00Z

🦋 Changeset detected

Latest commit: e9d68a7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2026-04-30T18:50:00Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Apr 30, 2026 6:50pm

pkg-pr-new · 2026-04-30T18:52:49Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8436

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8436

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8436

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8436

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8436

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8436

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8436

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8436

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8436

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8436

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8436

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8436

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8436

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8436

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8436

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8436

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8436

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8436

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8436

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8436

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8436

commit: e9d68a7

coderabbitai · 2026-04-30T18:53:58Z

📝 Walkthrough

Walkthrough

This pull request adds diagnostic instrumentation across the Clerk codebase to aid in debugging UserButton mounting behavior. A changeset entry file is created, and console.log statements are added to four locations: the Clerk.emit method to report listener counts and current identifiers, the useUserBase hook snapshot function to log loading status and fallback conditions with a conditional early return based on a fellBack flag, and the CoreUserContext HOC to report wrapped component identity and user information.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding diagnostics to instrument the userButton mount path.
Description check	✅ Passed	The description is directly related to the changeset, explaining the diagnostic purpose and the specific console.log additions across three files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Review rate limit: 2/5 reviews remaining, refill in 33 minutes and 3 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/clerk-js/src/core/clerk.ts`:
- Around line 3238-3253: The DIAG console logs in the Clerk emit path leak
internal identifiers and run on a hot path; wrap the diagnostic logging in a
non-production/explicit diagnostic flag check (e.g., only log when a process/env
flag like CLERK_DIAG_ENABLED or an internal config boolean is true) and stop
logging raw IDs—either remove userId/sessionId/clientId or redact them (e.g.,
boolean presence or truncated/sanitized values) before logging; apply the same
gated/sanitized change to the other diagnostic console.log sites referenced in
useUserBase and withCoreUserGuard and ensure the guard references the same
flag/config accessor used here (the block around the console.log in the method
that iterates this.#listeners).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 88fefe42-c3f3-46cf-8334-5b13748c4d1f

📥 Commits

Reviewing files that changed from the base of the PR and between 7680859 and e9d68a7.

📒 Files selected for processing (4)

.changeset/diag-userbutton-mount.md
packages/clerk-js/src/core/clerk.ts
packages/shared/src/react/hooks/base/useUserBase.ts
packages/ui/src/contexts/CoreUserContext.tsx

coderabbitai · 2026-04-30T18:54:01Z

+      // DIAG: instrument userButton mount regression
+      // eslint-disable-next-line no-console
+      console.log('[CLERK_DIAG] clerk.#emit', {
+        listeners: this.#listeners.length,
+        userId: this.user?.id ?? null,
+        sessionId: this.session?.id ?? null,
+        clientId: this.client?.id ?? null,
+        sessionsOnClient: this.client?.sessions?.length ?? 0,
+      });
      for (const listener of this.#listeners) {
        listener(resources);
      }
+    } else {
+      // DIAG: emit was skipped because client is unset
+      // eslint-disable-next-line no-console
+      console.log('[CLERK_DIAG] clerk.#emit skipped (no client)');


⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Remove or hard-gate [CLERK_DIAG] logs before merge

Line 3240 logs identifiers (userId, sessionId, clientId) on every emit. This is a merge blocker: accidental merge would leak internal identifiers into browser/CI logs and add noisy hot-path logging. Please gate these diagnostics behind an explicit non-production flag (or remove before merge), and apply the same guard to the matching [CLERK_DIAG] logs in useUserBase and withCoreUserGuard.

As per coding guidelines: "Implement proper logging with different levels" and "validate all inputs and sanitize outputs."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed. In `@packages/clerk-js/src/core/clerk.ts` around lines 3238 - 3253, The DIAG console logs in the Clerk emit path leak internal identifiers and run on a hot path; wrap the diagnostic logging in a non-production/explicit diagnostic flag check (e.g., only log when a process/env flag like CLERK_DIAG_ENABLED or an internal config boolean is true) and stop logging raw IDs—either remove userId/sessionId/clientId or redact them (e.g., boolean presence or truncated/sanitized values) before logging; apply the same gated/sanitized change to the other diagnostic console.log sites referenced in useUserBase and withCoreUserGuard and ensure the guard references the same flag/config accessor used here (the block around the console.log in the method that iterates this.#listeners).

jacekradko · 2026-04-30T19:00:40Z

Closing — the userButton mount regression we set out to instrument resolved itself externally between runs at 17:52 and 18:25 UTC today, with no JS-side code change in that window. That's confirmation the cause was environmental (FAPI deploy / instance config / runner image), not in this repo's source. Diagnostic isn't needed since the symptom is gone.

DIAG: log userButton mount path (do not merge)

e9d68a7

github-actions Bot added clerk-js ui labels Apr 30, 2026

vercel Bot deployed to Preview April 30, 2026 18:50 View deployment

coderabbitai Bot reviewed Apr 30, 2026

View reviewed changes

jacekradko closed this Apr 30, 2026

jacekradko deleted the jacek/diag-userbutton-mount branch April 30, 2026 19:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DIAG: instrument userButton mount path (do not merge)#8436

DIAG: instrument userButton mount path (do not merge)#8436
jacekradko wants to merge 1 commit intomainfrom
jacek/diag-userbutton-mount

jacekradko commented Apr 30, 2026

Uh oh!

changeset-bot Bot commented Apr 30, 2026

Uh oh!

vercel Bot commented Apr 30, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Apr 30, 2026

Uh oh!

coderabbitai Bot commented Apr 30, 2026

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot Apr 30, 2026

Uh oh!

jacekradko commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jacekradko commented Apr 30, 2026

Uh oh!

changeset-bot Bot commented Apr 30, 2026

🦋 Changeset detected

Uh oh!

vercel Bot commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Apr 30, 2026

Uh oh!

coderabbitai Bot commented Apr 30, 2026

Walkthrough

Estimated code review effort

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

jacekradko commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel Bot commented Apr 30, 2026 •

edited

Loading