Troubleshooting

Wake phrase not matching

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.

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.
  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.
  • 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

Error reference

Every typed error the Extentos SDK can return — ConnectError, CaptureError, AudioError, TransportError, the ExtentosError umbrella, and the Meta-DAT DeviceSessionError — with their payload fields and meaning. Lifecycle operations return ExtentosResult<T, E> with these concrete failure variants rather than throwing; pattern-match them. Generated from the Rust core.

Voice triggers

Wire a voice command on the glasses to an action in your app. Works on Meta Ray-Ban via the phone's speech recognizer over Bluetooth. Phrases auto-surface on the connection page and the simulator's click-to-fire panel.

The assistant runtime

Build a voice assistant on smart glasses with glasses.assistant — wake/sleep, tools, vision, barge-in, memory, on the managed AI gateway. Phase-4 preview.

Glasses won't connect

Fix common first-connection failures on Meta Ray-Ban — no pairing dialog, session won't start, the DAT auth callback never fires, or an immediate disconnect.

Photo capture fails

Fix capturePhoto() returning an error or no image on Meta Ray-Ban — CAMERA permission, thermal-critical, folded hinges, coexistence, and the camera toggle.

On this page

SymptomsQuick checklist (the things to verify first)Related