Add note about user.reload() method to clarify use

[SarahSoutoul]

🔎 Previews:

• https://clerk.com/docs/pr/ss-docs-11140/guides/development/add-onboarding-flow
• https://clerk.com/docs/pr/ss-docs-11140/reference/javascript/user

What does this solve?

This PR comes after user feedback around the use of the user.reload() method in this page: https://clerk.com/docs/guides/development/add-onboarding-flow. User feedback can be found here. This PR adds a note to clarify its use and links to the corresponding page with more info.

What changed?

• Added note callout + link

Checklist

• I have clicked on "Files changed" and performed a thorough self-review
• All existing checks pass

[vercel]

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

Project	Deployment	Preview	Updated (UTC)
clerk-docs	Ready	Preview	Dec 2, 2025 8:15pm

[alexisintech]

this is good information, i agree, but i'm a little confused why user.reload() is called in the first place (and maybe that's also why the user was confused) - we aren't using the user object anywhere, so why do we need to reload it?

@royanger originally wrote this guide, maybe he has some insight

[royanger]

We are using the session claims in Middleware and other places. Once the metadata is mutated via BAPI, the user will need an updated session token with updated claims. This happens one of 3 ways:

• user signs out and back in (terrible UX obviously)
• user waits up to 1 minute for normal session token refresh (not great UX either)
• programmatically use user.reload() to get updated metadata/session claims so the user can now leave onboarding/move to another step/etc.

Until one of the happens, the Middleware (and anything else that checks metadata/session claims) will have stale data.

[SarahSoutoul]

We are using the session claims in Middleware and other places. Once the metadata is mutated via BAPI, the user will need an updated session token with updated claims. This happens one of 3 ways:

• user signs out and back in (terrible UX obviously)
• user waits up to 1 minute for normal session token refresh (not great UX either)
• programmatically use user.reload() to get updated metadata/session claims so the user can now leave onboarding/move to another step/etc.

Until one of the happens, the Middleware (and anything else that checks metadata/session claims) will have stale data.

Thanks for explanation @royanger - do you think the callout is good /accurate info?

[alexisintech]

We are using the session claims in Middleware and other places. Once the metadata is mutated via BAPI, the user will need an updated session token with updated claims. This happens one of 3 ways:

• user signs out and back in (terrible UX obviously)
• user waits up to 1 minute for normal session token refresh (not great UX either)
• programmatically use user.reload() to get updated metadata/session claims so the user can now leave onboarding/move to another step/etc.

Until one of the happens, the Middleware (and anything else that checks metadata/session claims) will have stale data.

ahhh that's right, it forces a token refresh and we're using the token in the app in middleware and other places - got it!

[royanger]

There is a code comment already (// Reloads the user's data from the Clerk API)so I would do one of two things:

1. Rewrite that a bit to be more explicit
2. Remove that and replace with a callout with a variation of the info from the feedback.

[alexisintech]

We are using the session claims in Middleware and other places. Once the metadata is mutated via BAPI, the user will need an updated session token with updated claims. This happens one of 3 ways:

• user signs out and back in (terrible UX obviously)
• user waits up to 1 minute for normal session token refresh (not great UX either)
• programmatically use user.reload() to get updated metadata/session claims so the user can now leave onboarding/move to another step/etc.

Until one of the happens, the Middleware (and anything else that checks metadata/session claims) will have stale data.

Thanks for explanation @royanger - do you think the callout is good /accurate info?

imo, i don't think it's quite on the money, i think we can frame it slightly better to emphasize that we call it to force a token refresh, and then explain why we need to force the token refresh

[alexisintech]

There is a code comment already (// Reloads the user's data from the Clerk API)so I would do one of two things:

1. Rewrite that a bit to be more explicit
2. Remove that and replace with a callout with a variation of the info from the feedback.

i agree with part of 2 - update the callout with a variation of the info from the feedback

but i say we still keep the code comment. maybe update the code comment to say
// Forces a token refresh and refreshes the User object

[alexisintech]

note we should probably also update https://clerk.com/docs/reference/javascript/user#reload
to include some of this helpful information. i noticed it doesn't even mention that it will force a session token refresh.

we have some of that info here: https://clerk.com/docs/guides/sessions/force-token-refresh#user-reload

whatever we come up with, I think it'd be good to align the two

[SarahSoutoul]

Have made some updates Refinements post feedback. Let me know your thoughts @alexisintech @royanger.

[alexisintech]

posted a small update, to give the information some context so that the user attributes meaning to the copy - otherwise they might be like "what is this, why am i reading this, why is it important" and skip over it !