signUp.finalize() lacks the stale-client reload guard that signIn.finalize() has — FAPI propagation lag becomes a silent sign-out

[PeggyWang0]

Preliminary checks

• I have reviewed the documentation and existing issues; I could not find this reported (searched for setActive + client.reload, "sessions.some", and the SignIn guard's comment text).

Package + version

@clerk/clerk-js (observed via @clerk/expo on React Native; verified present on main as of 2026-08-11)

Description

SignUpFuture.finalize() is missing the stale-client reload guard that SignInFuture.finalize() has. On a phone-OTP sign-up, FAPI propagation lag between the verification response and the piggybacked Client turns a successful sign-up into a silent sign-out.

Mechanism:

1. setActive({ session: createdSessionId }) resolves a string session id against the local client and coerces a miss to null:

// packages/clerk-js/src/core/clerk.ts
if (typeof session === 'string') {
  session = (this.client.sessions.find(x => x.id === session) as SignedInSessionResource) || null;
}

…and setActive({ session: null }) is the sign-out path. So a session id that is real on the server but not yet visible in the in-memory client is treated as "sign out", with no error surfaced to the caller.

2. SignInFuture.finalize() protects against exactly this with a client reload (packages/clerk-js/src/core/resources/SignIn.ts, ~L1538):

// Reload the client if the created session is not in the client's sessions. This can happen during modal SSO
// flows where the in-memory client does not have the created session.
if (SignIn.clerk.client && !SignIn.clerk.client.sessions.some(s => s.id === this.#resource.createdSessionId)) {
  await SignIn.clerk.client.reload();
}

this.#canBeDiscarded = true;
await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });

3. SignUpFuture.finalize() has no such guard (packages/clerk-js/src/core/resources/SignUp.ts, ~L1224):

async finalize(params?: SignUpFutureFinalizeParams): Promise<{ error: ClerkError | null }> {
  const { navigate } = params || {};
  return runAsyncResourceTask(this.#resource, async () => {
    if (!this.#resource.createdSessionId) {
      throw new Error('Cannot finalize sign-up without a created session.');
    }

    this.#canBeDiscarded = true;
    await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
  });
}

The stale-client condition the SignIn comment describes is not SSO-specific — on mobile (Expo / React Native, phone-code strategy) the verification response's piggybacked client regularly lags the just-created session under real-world cellular latency, and sign-up is the flow where this hits hardest: it strikes brand-new users at the exact moment of a successful verification.

Real-world impact

Production React Native (Expo) app, phone-OTP-only auth. Before we wrapped finalize with our own reload-until-visible guard app-side, roughly a quarter of new sign-ups over a 14-day window hit a stuck state downstream of this silent sign-out — the user lands on the next onboarding screen already signed out, and every subsequent getToken() throws Unable to authenticate the request, you need to supply an active session. After shipping the app-side guard, the error class disappeared from our telemetry entirely, which is strong evidence the reload guard is the correct fix.

Expected behavior

Either:

• SignUpFuture.finalize() mirrors the SignIn guard (reload the client when createdSessionId is not visible yet), or
• setActive({ session: '<id>' }) errors when the id cannot be resolved, instead of silently signing the user out.

Proposed fix

   async finalize(params?: SignUpFutureFinalizeParams): Promise<{ error: ClerkError | null }> {
     const { navigate } = params || {};
     return runAsyncResourceTask(this.#resource, async () => {
       if (!this.#resource.createdSessionId) {
         throw new Error('Cannot finalize sign-up without a created session.');
       }

+      // Reload the client if the created session is not in the client's sessions. Mirrors
+      // SignInFuture.finalize(): the in-memory client can lag the just-created session
+      // (modal SSO flows on web; piggybacked-client propagation lag on mobile).
+      if (SignUp.clerk.client && !SignUp.clerk.client.sessions.some(s => s.id === this.#resource.createdSessionId)) {
+        await SignUp.clerk.client.reload();
+      }
+
       this.#canBeDiscarded = true;
       await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
     });
   }

Related prior art for the same shared-client race family: #8548 (avoid re-preparing pending code verifications) and #9225 (coalesce concurrent first/second factor preparations).

Happy to open a PR with the change above if the approach looks right to the team.