Skip to content

feat(ui): show a support reference on a failed verification check, and start over after an expired one - #10884

Open
zourzouvillys wants to merge 1 commit into
mainfrom
theo/protect-check-timeout-retry-ref
Open

zourzouvillys wants to merge 1 commit into
mainfrom
theo/protect-check-timeout-retry-ref

Conversation

@zourzouvillys

Copy link
Copy Markdown
Contributor

Description

When a verification check during sign-in or sign-up didn't complete in time, the card showed "Verification didn't complete in time. Please try again." Two problems:

  1. "Try again" could not succeed. Retry reloaded the attempt, which returns the same expired check, so it failed straight away with the same error. Now, for this error only, "Try again" returns to the start of the flow. Submitting again starts a new attempt, and that attempt gets a new check. Every other failure (script failed to load, check failed to run, and so on) still retries the same check in place, as before.
  2. Nothing to give support. Any error on the verification card now shows a copyable reference under the button: the sign-in or sign-up id and the error code, e.g. sia_… · protect_check_timed_out. It reuses the existing "Reference" label. Three new appearance elements style it: protectCheckReferenceBox, protectCheckReferenceLabel and protectCheckReference.

What this does not change

  • Custom flows using the verification modal. On failure the modal still closes, and the call rejects with a ClerkRuntimeError whose code is protect_check_timed_out. A custom flow already holds signIn.id / signUp.id, which is the same reference, and calling create() again gets a new check.
  • Mosaic. Its protect-check block is presentational only: no runner is wired to it yet, so there is nothing to change there.

How to test

Get a sign-in into a verification check that has expired (expiresAt in the past). The card shows the error, the reference, and "Try again". Clicking it returns to the sign-in start.

Verification

  • pnpm exec vitest run on SignInProtectCheck, SignUpProtectCheck and ProtectCheckModal: 3 files passed, 67 tests passed.
  • Full @clerk/ui suite (pnpm exec vitest run in packages/ui): 204 files passed; 2992 tests passed, 9 skipped, 12 todo.
  • Negative control: with the source changes reverted and the new tests kept, the 6 new tests fail and the other 56 pass.
  • pnpm type-check in packages/ui: clean. eslint --quiet on the changed files: clean.
  • pnpm build: not run.

Checklist

  • pnpm test runs as expected (the @clerk/ui suite; see Verification).
  • pnpm build runs as expected.
  • (If applicable) JSDoc comments have been added or updated for any package exports
  • (If applicable) Documentation has been updated: the new appearance elements may want a mention.

Type of change

  • 🐛 Bug fix
  • 🌟 New feature
  • 🔨 Breaking change
  • 📖 Refactoring / dependency upgrade / documentation
  • other:

@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: ee82297

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

This PR includes changesets to release 2 packages
Name Type
@clerk/ui Minor
@clerk/chrome-extension Patch

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

vercel Bot commented Nov 18, 2026

Copy link
Copy Markdown

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

Project Deployment Actions Updated
clerk-js-sandbox Ready Ready Preview Nov 18, 2026 12:47am UTC
mosaic-docs Error Error Nov 18, 2026 12:47am UTC
swingset Ready Ready Preview Nov 18, 2026 12:47am UTC

Request Review

@github-actions github-actions Bot added the ui label Nov 18, 2026
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The Protect Check runner now exposes an error code and resource ID. When a check times out, retry invokes a flow-start callback instead of rerunning the challenge. Sign-in and sign-up supply that callback. The error card displays a support reference when an error and reference value are available. Appearance configuration adds selectors for the reference box, label, and content. New tests cover timeout and other retry behavior, plus support-reference display.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: wobsoriano, mwickett, alexcarpenter

Merge Risk: Minimal · up to ee822

The change adds a copyable support reference to failed verification cards and sends users back to the start of sign-in or sign-up after an expired check. The inspected code gives no sign of a retry loop or broken styling hooks. The only visible blocker is the PR title, which exceeds the 100-character header limit and needs shortening before merge.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title describes the two main behavior changes in the changeset: a support reference shown on a failed verification card, and returning to the flow start after an expired protect check. Both are pr…
Description check Passed The description explains the problem, the retry behavior change for protect_check_timed_out, the new copyable reference and its three appearance elements, what is unchanged for custom flows and Mosaic…
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.
Full details: Title check

Explanation

The title describes the two main behavior changes in the changeset: a support reference shown on a failed verification card, and returning to the flow start after an expired protect check. Both are present in the raw summary and the PR objectives, so the title matches the main change.

Full details: Description check

Explanation

The description explains the problem, the retry behavior change for protect_check_timed_out, the new copyable reference and its three appearance elements, what is unchanged for custom flows and Mosaic, test steps, and verification results. It matches the changeset closely.

Finishing Touches

Fix failing CI checks

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Linked repositories: Some configured repositories could not be included in this review. Cross-repository analysis may be incomplete. Please check linked-repository access and settings.

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: clerk/javascript
  • Branch: main
  • File: .coderabbit.yaml
  • Commit: 9f21762
  • Layers: Repository YAML (base), Organization UI (inherited)
  • Review profile: ASSERTIVE
  • Plan: Team
  • Run ID: 148051d1-6595-462c-bbdb-8fd5505be969
Commits

Reviewing files that changed from the base of the PR and between 9f21762 and ee82297.

Files selected for processing: 9

  • .changeset/protect-check-expired-retry.md
  • packages/ui/src/components/ProtectCheck/ProtectCheckCard.tsx
  • packages/ui/src/components/SignIn/SignInProtectCheck.tsx
  • packages/ui/src/components/SignIn/__tests__/SignInProtectCheck.test.tsx
  • packages/ui/src/components/SignUp/SignUpProtectCheck.tsx
  • packages/ui/src/components/SignUp/__tests__/SignUpProtectCheck.test.tsx
  • packages/ui/src/customizables/elementDescriptors.ts
  • packages/ui/src/hooks/useProtectCheckRunner.ts
  • packages/ui/src/internal/appearance.ts
Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

Included review availability: This review used your included allowance. 9 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

@github-actions

Copy link
Copy Markdown
Contributor

API Changes Report

Generated by Break Check on 2026-11-18T00:51:26.266Z

Summary

Metric Count
Packages analyzed 20
Packages with changes 1
🔴 Breaking changes 0
🟡 Non-breaking changes 1
🟢 Additions 0

🤖 This report was reviewed by claude-sonnet-4-6.


@clerk/ui

Current version: 1.43.0
Recommended bump: MINOR → 1.44.0

Subpath ./internal

🟡 Non-breaking Changes (1)

Modified: ElementsConfig
// ... 116 unchanged lines elided ...
    actionBlockedTraceIdBox: WithOptions;
    actionBlockedTraceIdLabel: WithOptions;
    actionBlockedTraceId: WithOptions;
+   protectCheckReferenceBox: WithOptions;
+   protectCheckReferenceLabel: WithOptions;
+   protectCheckReference: WithOptions;
    verificationLinkStatusBox: WithOptions;
    verificationLinkStatusIconBox: WithOptions;
    verificationLinkStatusIcon: WithOptions;
// ... 511 unchanged lines elided ...

Static analyzer: Breaking change in type alias ElementsConfig: Type changed: {button:import("@clerk/ui").~WithOptions<string>;input:import("@clerk/ui").~WithOptions;checkbox:import("@clerk/ui").~W… → {button:import("@clerk/ui").~WithOptions<string>;input:import("@clerk/ui").~WithOptions;checkbox:import("@clerk/ui").~W…

🤖 AI review (reclassified as non-breaking) (85%): The diff elides 553 vs 556 lines, indicating 3 new properties were added to ElementsConfig. ElementsConfig is used only as a mapped-type source in the output type Elements, not as an input position consumers construct, so adding new keys is non-breaking; however, since the elided lines prevent full inspection, this is treated as an addition of keys rather than a structural break. No existing keys appear removed or changed in the visible portions.


Report generated by Break Check

Last ran on ee82297.

@pkg-pr-new

pkg-pr-new Bot commented Nov 18, 2026

Copy link
Copy Markdown

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@10884

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@10884

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@10884

@clerk/expo

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

@clerk/expo-biometrics

npm i https://pkg.pr.new/@clerk/expo-biometrics@10884

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@10884

@clerk/expo-native-components

npm i https://pkg.pr.new/@clerk/expo-native-components@10884

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/mosaic

npm i https://pkg.pr.new/@clerk/mosaic@10884

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: ee82297

@blacksmith-sh

blacksmith-sh Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Differs Expired sign-in check: reference and start over

Differs — The reference shows, but Try again clears the error and leaves a blank verification card with no button or form; it never returns to the sign-in start, so no new attempt can be submitted.

Before · Recording

Recording

Watch full video · Original footage · 0:00 Sign in hits an expired check · 0:07 Try again after the expired check

After · Recording

Recording

Watch full video · Original footage · 0:00 Sign in hits an expired check · 0:07 Try again after the expired check

Merge-base

Expired error

This PR ee822974

Expired error

Merge-base

After Try again

This PR ee822974

After Try again

Also checked · 1 match · 1 differs

Differs Expired sign-up check: reference and start over
Matches Other failures still retry in place

Warning

Doesn't do what was asked

Expired sign-up check: reference and start over

The sign-up card shows the sua_ id · protect_check_timed_out reference, but Try again leaves a blank verification card instead of returning to the sign-up form.

Merge-base

Expired error

This PR ee822974

Expired error

Merge-base

After Try again

This PR ee822974

After Try again

Caution

New issue found while testing

Blank card after retry in the sign-in modal too

In the openSignIn modal (virtual routing), Try again on an expired check also leaves an empty verification card; navigateToFlowStart is a no-op when called from inside the protect-check route.

Proof on ee822974 · mocked: Protect challenge SDK (the real challenge script is server-chosen; a routed sdk_url stands in that fail...), Clerk Frontend API (staging instance) (the sandbox's hosted instance does not issue Protect checks on demand, so sign-i...) · Did Proof get it right? Yes · No

View full Proof report · React 👎 or comment @codesmith dismiss this proof to dismiss

This branch was successfully deployed

2 active deployments
Preview – swingset — ee822974 Deployed Nov 18, 2026 by vercel[bot]
Preview – clerk-js-sandbox — ee822974 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant