---
title: Wake phrase not matching
description: You subscribed to glasses.audio.transcriptions() and matched a wake phrase, but the handler doesn't run when you say it. Common causes and fixes.
type: troubleshooting
platform: all
related:
  - /docs/reference/errors
  - /docs/guides/voice-triggers
  - /docs/concepts/assistant
---

Your handler subscribes to `glasses.audio.transcriptions()` and matches strings against the Final transcripts, but the `if` branch that fires your business logic doesn't run. Most-common causes:

## Symptoms

- Wake phrase matches in the browser simulator but not on real glasses (or vice-versa)
- Wake phrase matches intermittently — sometimes fires, sometimes silent
- Wrong wake phrase wins — the user says phrase A and the handler reacts as if phrase B was said
- Final transcripts never arrive at all
- Partial transcripts arrive but no Final
- Transcripts arrive in the wrong case / with punctuation / with apostrophes that break string matching

## Quick checklist (the things to verify first)

1. **`glasses.toggles.state` snapshot.** All four of these must be on for transcripts to flow: `transcription_enabled = true`, `audio_capture_enabled = true`, `privacy_mode = false`, `listening_mode != "off"`. Any one closed and you'll see no Final transcripts.
2. **You're matching on `isFinal`, not partial.** Partial transcripts emit 5–20 per second and partial text can match a wake phrase mid-utterance. Pattern-match the `.final(...)` variant before string comparison.
3. **Casing + punctuation normalization on the read side.** The library does not normalize — `transcript.text` is what the recognizer returned, verbatim. Match against `transcript.text.lowercased().replace(...)` to cover variance. See `searchDocs(topic: 'voice_ux_guide')` for the canonical normalizer.
4. **You called `getVoiceCommandGuidance` on the phrases.** The tool catches homophone collisions, ambiguity against existing phrases, hard-to-recognize words, and Meta wake-word conflicts — issues the runtime can't surface back as "didn't match."
5. **The phrase is registered `WhenDormant` while an assistant session is active.** A `glasses.voice.onPhrase` registration defaults to `VoiceScope.WhenDormant` — it won't fire during an active `glasses.assistant` conversation. Use `VoiceScope.Always` if the phrase must fire mid-conversation. See [the assistant runtime](/docs/concepts/assistant).
6. **`getEventLog(filter: 'voice')`** in the simulator session. If you see Final transcripts in the log but your handler's `if` doesn't run, the string-match logic is the culprit. If you don't see Final transcripts at all, the toggle state or the connection is the culprit.

## Related

- `searchDocs(topic: 'voice_ux_guide')` — phrase design rules + the canonical normalize() helper
- `searchDocs(topic: 'toggles')` — full toggle gating model
- `getCapabilityGuide(feature: 'transcription_incremental')` — call shape + gotchas
- `getCodeExample(pattern: 'voice_qa_assistant')` — full working composition to peel from