## TL;DR
Missing codes are a delivery problem far more often than an app problem, and "invalid code" is usually the user typing an old one. Check the number on file, wait out carrier delays, and switch the delivery channel before resending into the void. Every resend invalidates the previous code, so rapid-fire resending is how users end up with five codes and none of them work.

## The query

```text
"I didn't receive the verification code" troubleshooting
```

## Use this when

- No SMS code arrives
- The code arrives but always shows as invalid
- Codes arrive minutes late and have expired
- The user changed phone numbers
- You are writing the verification macro

## Not for

- Password reset emails not arriving
- First-time two-factor setup
- Codes for a different service
- Account lockouts

## Steps

### 1. Verify the destination number or address

Read back the phone number or email on file digit by digit. Changed numbers, ported carriers, and typo'd digits are the top causes. Never send a code to a new number the user just typed in chat without verifying it another way.

Expected output: the destination confirmed correct, or the mismatch found.

### 2. Wait, then resend exactly once

SMS can lag 2 to 10 minutes on congested carriers. Tell the user to wait five full minutes, then trigger one resend, and to use only the newest code. Warn them explicitly: each new code kills the old ones.

Expected output: one fresh code in flight and the newest-only rule understood.

### 3. Check carrier and device blocks

Ask them to check blocked numbers, spam filters, and whether short codes are blocked on their plan. Some carriers silently drop automated texts, and some plans block premium or short-code SMS entirely. An alternate number on a different carrier is a fast test.

Expected output: a block found and lifted, or the carrier ruled out.

### 4. Switch the delivery channel

If SMS keeps failing, offer the code by voice call or email instead, whichever your system supports. Do not keep hammering the broken channel. One working channel beats three broken retries.

Expected output: the code delivered through the alternate channel.

### 5. For authenticator apps, check the clock

If they use an authenticator app and codes always read invalid, the phone's clock is off. Time-based codes need the clock accurate within about 30 seconds. Have them enable automatic date and time in phone settings and try the next code.

Expected output: codes validate after the clock syncs.

## Ready-to-use message

```text
Let's get you that code. First, can you confirm the number we
have ends in [last two digits]?

Phone carriers can be slow, so wait 5 full minutes. Then I'll
send one fresh code. Important: use only the newest one, since
each new code cancels the older ones.

Also check your blocked numbers and spam folder for texts. If
nothing arrives, I can send the code by voice call instead.
```

## Variant phrasings

### verification code not received by text

Steps 1 through 4. Number check, one patient resend, block check, channel switch.

### sms code never arrives support

Steps 1 and 3 first. Wrong number or carrier filtering covers most of these.

### authenticator code always invalid

Step 5 on its own. It is the clock, nearly every time.

## Why it happens

The code system has two halves that fail independently: generating the code and delivering it. Users experience both as "your code does not work," but the fixes are opposites. Delivery failures need patience and channel switches, while invalid-code failures need the newest-code rule or a clock fix. Diagnosing which half broke before acting is the whole skill.

## Edge cases

- User is abroad roaming: SMS delivery to roaming numbers is unreliable. Switch to email or voice call immediately instead of debugging.
- VoIP numbers like Google Voice: many verification systems block them as fraud-prone. Ask for a real mobile number.
- Codes arrive but expired: the delay exceeds the code lifetime. Lengthen the expiry on your side if this recurs, and switch channels meanwhile.
- User requests codes for someone else's account: do not. Verification codes go only to the verified destination on file, full stop.
- Landline entered as a mobile: SMS to a landline goes nowhere. Offer the voice-call option, which is built for exactly this.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qD2n8y8r1ZDGbKjkRPA-fg