HeyPuter/puter · error · HttpError

phone_verification_required

phone_verification_required

Error message

Please verify your phone number to continue

What it means

Raised by `assertVerifiedAccount` when the user row has `requires_phone_verification` truthy. The account must complete phone verification before the guarded route proceeds. The `as never` cast on the legacy code signals this branch is forward-looking / not fully wired into the error-code registry yet.

Source

Thrown at src/backend/core/http/middleware/gates.ts:377

 * gate rejects.
 */
export const assertVerifiedAccount = (
    user:
        | {
              requires_email_confirmation?: unknown;
              email_confirmed?: unknown;
              requires_phone_verification?: unknown;
              requires_card_verification?: unknown;
          }
        | undefined,
): void => {
    if (user?.requires_email_confirmation && !user?.email_confirmed) {
        throw new HttpError(403, 'Please confirm your email to continue', {
            legacyCode: 'email_confirmation_required',
        });
    }
    if (user?.requires_phone_verification) {
        throw new HttpError(
            403,
            'Please verify your phone number to continue',
            {
                legacyCode: 'phone_verification_required' as never,
            },
        );
    }
    if (user?.requires_card_verification) {
        throw new HttpError(403, 'Please verify your card to continue', {
            legacyCode: 'card_verification_required' as never,
        });
    }
};

export const assertNotSuspended = (
    user: { suspended?: unknown } | undefined,
): void => {
    if (user?.suspended) {

View on GitHub (pinned to 908ec23eda)

Solutions

  1. Complete the phone verification flow for the account.
  2. As admin, clear `requires_phone_verification` if the gate is not intended.
  3. Confirm phone verification isn't required before surfacing the gated feature to the user.
Defensive patterns

Strategy: try-catch

Try / catch

try { await call(); }
catch (e) {
  if (e.code === 'phone_verification_required') { routeToPhoneVerification(); return; }
  throw e;
}

Prevention

When it happens

Trigger: An account flagged `requires_phone_verification` calls any route guarded by `assertVerifiedAccount` before completing phone verification.

Common situations: A compliance/billing feature enabled phone gating for an account or region; the flag was set by an admin/automation and the user hasn't completed the flow.

Related errors

AI-assisted analysis of HeyPuter/puter@908ec23eda (2026-08-12). Data as JSON: /api/errors/f49333cb9e3f358e. Report an issue: GitHub.