# debugging

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

Skill by Meta. Category: Testing.

## Install

Project (for this project only):

```sh
npx skills add facebook/meta-wearables-dat-ios --skill debugging
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add facebook/meta-wearables-dat-ios --skill debugging -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 9. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/facebook/meta-wearables-dat-ios/debugging)

## Source

[Open the source](https://github.com/facebook/meta-wearables-dat-ios/tree/HEAD/plugins/mwdat-ios/skills/debugging). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: debugging
description: Common issues, Developer Mode, version compatibility, state machine diagnosis
---

# 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

```text
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

1. Open Meta AI app on phone
2. Go to Settings → (Your connected glasses)
3. Find "Developer Mode" toggle
4. Toggle ON
5. 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

```text
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](https://wearables.developer.meta.com/docs/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](https://wearables.developer.meta.com/docs/knownissues) page for the current list.

## Adding debug logging

```swift
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.

## Checklist

- [ ] Developer Mode enabled in Meta AI app
- [ ] Meta AI app updated to compatible version
- [ ] Glasses firmware updated to compatible version
- [ ] Internet connection available for registration
- [ ] Bluetooth enabled on phone
- [ ] Correct URL scheme configured in Info.plist, and `MWDAT` > `AppLinkURLScheme` matches it
- [ ] URL callback handler forwards `metaWearablesAction` links to `Wearables.shared.handleUrl(_:)`
- [ ] Background modes enabled (`processing`, `bluetooth-central`, `bluetooth-peripheral`, `external-accessory`)
- [ ] `UISupportedExternalAccessoryProtocols` contains `com.meta.ar.wearable`
- [ ] `NSBluetoothAlwaysUsageDescription`, `NSLocalNetworkUsageDescription`, and `NSBonjourServices` present

## Links

- [Known issues](https://wearables.developer.meta.com/docs/knownissues)
- [Version dependencies](https://wearables.developer.meta.com/docs/version-dependencies)
- [Troubleshooting discussions](https://github.com/facebook/meta-wearables-dat-ios/discussions)
````

- Previous: [dat-conventions](https://syn4pse.dev/terminal/meta-ios-dat-conventions.md)
- Next: [display-access](https://syn4pse.dev/terminal/meta-ios-display-access.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
