debugging

Common issues, Developer Mode, version compatibility, state machine diagnosis

npx skills add https://github.com/facebook/meta-wearables-dat-ios --skill debugging

Debugging (iOS)

Diagnose common setup, registration, and streaming issues in DAT SDK integrations.

If local DAT Inspector MCP tools are available, use the live-debugging-mcp skill before changing app code. Prefer get_dat_readiness, get_companion_boundary_diagnosis, and get_device_path to separate app bugs from Meta AI app/device boundary issues using read-only DAT evidence.

Quick diagnosis

Device not connecting?
│
├── Is Developer Mode enabled? → Enable in Meta AI app settings
│
├── Is device registered? → Check registration state
│
├── Is device in range? → Bluetooth on, glasses powered on
│
├── Is the app registered? → Check registrationStateStream()
│
└── Stream stuck in waitingForDevice? → Check device availability

Developer Mode

Developer Mode must be enabled for 3P apps to access device features.

Enabling Developer Mode

Open Meta AI app on phone
Go to Settings → (Your connected glasses)
Find "Developer Mode" toggle
Toggle ON
Device may restart

Symptoms of Developer Mode disabled

Registration completes but device never connects
Stream stuck in waitingForDevice
Permission requests fail or never appear

Watch for

Developer Mode toggles off after firmware updates — re-enable it
Developer Mode is per-device — enable for each glasses pair
Some features need additional permissions beyond Developer Mode

Stream state issues

Expected flow

stopped → waitingForDevice → starting → streaming → stopped

Stuck in waitingForDevice

Device not in range or not connected
Device not reporting availability
DeviceSelector not matching any device

Unexpected stop

Device disconnected (out of range, battery died)
Channel closed by device
Error in frame processing

Version compatibility

Ensure compatible versions of SDK, Meta AI app, and glasses firmware. See version dependencies for the current compatibility matrix.

Known issues

Issue	Workaround
No internet → registration fails	Internet required for registration
Streams started with glasses doffed pause when donned	Unpause by tapping the side of the glasses
A single touchpad tap pauses an active stream	Tap again to resume; keep the last frame on screen while `StreamState` is `.paused`

See the public known issues page for the current list.

Adding debug logging

import os

private let logger = Logger(subsystem: "com.yourapp", category: "Wearables")

// In your streaming code:
logger.debug("Stream state changed to: \(state)")
logger.error("Stream error: \(error)")

Live MCP evidence

When the developer has a local DAT debug server connected to the agent:

Start with get_sdk_state and get_dat_readiness
Use get_companion_boundary_diagnosis for permission, app identity, device capability, device-selection, deeplink-return, and DAM/DWA-visible blockers
Use get_device_path to trace app -> DAT registration -> Meta AI app permissions -> device selection/link -> session -> stream
Ask the developer to reproduce the issue, then use wait_for_events with the narrowest category or source that matches the flow
Use export_diagnostic_bundle for redacted support handoff

Do not treat this as companion app introspection. It is diagnosis from app-visible DAT debug events.