Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

ClerkAPIError drops meta.lockout_expires_in_seconds from user_locked errors

Open Beginner friendly
  • Is something wrong?
#10,026 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
authentication

Research direction

Start in packages/shared/src/errors/clerkApiError.ts at the metadata parsing around lines 21-38, where ClerkAPIError builds meta from known keys. Trace how the raw user_locked response is converted to the public error, then verify that lockout_expires_in_seconds is preserved as lockoutExpiresInSeconds and remains available to callers.

Written by the indexing model from the issue text.

Description

Preliminary Checks
  • I have reviewed the documentation: https://clerk.com/docs
  • I have searched for existing issues: https://github.com/clerk/javascript/issues
  • I have not already reached out to Clerk support via email or Discord
  • This issue is not a question, general help request, or anything other than a bug report directly related to Clerk
Reproduction

The bug is visible in the source, no project needed: https://github.com/clerk/javascript/blob/main/packages/shared/src/errors/clerkApiError.ts#L21-L38

Publishable key

Not needed: the behavior does not depend on an instance, it is in the error parser.

Description

When an account reaches the user lockout threshold, the Frontend API answers the failed attempt with 403 user_locked and includes how long the lockout lasts in meta.lockout_expires_in_seconds. ClerkAPIError builds its meta from a fixed list of known keys (param_name, session_id, identifiers, zxcvbn, plan, …), so lockout_expires_in_seconds is dropped and the app cannot tell the user when they can try again.

Steps to reproduce:

  1. Enable user lockout on an instance (e.g. 10 attempts, 60 minutes).
  2. Sign in with a phone code and submit wrong codes until the attempt returns user_locked.
  3. Inspect the network response: errors[0].meta.lockout_expires_in_seconds is present (e.g. 3599).
  4. Inspect the thrown ClerkAPIResponseError: errors[0].meta has no lockout field.

Expected behavior:

ClerkAPIError.meta exposes the lockout duration (e.g. lockoutExpiresInSeconds), the same way ClerkAPIResponseError.retryAfter already exposes Retry-After for too_many_requests, so apps can show a countdown or hide "resend code" until the lockout ends.

Actual behavior:

The value is discarded during parsing. The only way to read it is to bypass the SDK and parse the raw response.

Environment
@clerk/shared 4.31.0 (also on main as of 2026-10-01)
@clerk/clerk-expo, React Native (Expo SDK), iOS and Android
Dominant language
TypeScript
Stars
1.8k
Forks
477
Avg merge
1d 18h
Merged PRs (30d)
287

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from clerk/javascript

All issues in clerk/javascript

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.