Logs and issue reports
Identify the failing stage, then collect its logs, versions, and reproduction steps. Distinguish build, QR download, App validation, Bluetooth startup, and business-execution failures.
Collect evidence for the failing stage#
| Phase | Where to look first | Also record |
|---|---|---|
| Compile or package | The terminal running build.py; preserve the first actual error. | Working directory, complete command, project name, and missing files or failed dependencies. |
| Studio Preview or Generate ZIP | Web logs, glasses-simulator logs, and packaging messages in Runtime Logs. | Both dropdown component selections, output ZIP, and whether packaging finished. |
| Phone QR download | App messages and whether the computer's LAN service is still running. | Scan time, current computer address/port, phone network, and download stage. |
| App download, validation, and authorization | App download, validation, or permission messages. Test builds with diagnostics can export plugin diagnostic logs. | ZIP filename, application version, authorization actions, and whether a local application was saved. |
| Bluetooth installation or glasses runtime | App installation/startup results, physical glasses display, and available device diagnostics. | Connection state, App/firmware versions, and whether the original example also fails. |
| Customised business or cloud request | Web/GMP business log, and your own service log. | Request identification, operational name, time of dispatch and receipt, specific error. |
Handle C Host return values#
| Return value | Meaning | First response |
|---|---|---|
| GM_PLUGIN_EINVAL | Parameters, sizes, or data layouts are invalid. | Check pointers, lengths, enum ranges, and struct sizes. Correct the arguments first. |
| GM_PLUGIN_ENOTSUP / GM_PLUGIN_EVERSION | A capability is missing or the API version is incompatible. | Check capability bits, function tables, and target firmware. Provide a fallback; do not cast around incompatibility and keep calling. |
| GM_PLUGIN_EBUSY | Resources or samples are not available for the time being. | Follow the specific API's retry rules. If imu_read has no sample, return and try again in a later on_loop. |
| GM_PLUGIN_ENOMEM | Insufficient memory or output capacity. | Reduce resources or increase output capacity and clean up partial initialization. Do not repeatedly allocate in an infinite loop. |
| GM_PLUGIN_EIO | The device or transfer operation failed. | Use connection and lifecycle state to diagnose the failure. Make clear that this action has no success confirmation. |
| GM_PLUGIN_EPERM / GM_PLUGIN_ESTATE | The current context or state does not allow the operation. | Check start/stop order, sampling mode, and resource locks. Return to an allowed state before calling again. |
Where to start with Web Bridge errors#
| Error Category | Priority check | Next |
|---|---|---|
| PERMISSION_DENIED | Declarations, authorized scope, message channels, event types, and foreground state. | Correct the manifest or let the user authorize again. Keep features independent of that permission. |
| METHOD_NOT_FOUND / CAPABILITY_UNAVAILABLE | Methods and capabilities supported by the current host. | Query getCapabilities() and check versions. Hide unsupported actions or explain their unavailability. |
| RUNTIME_CLOSED | Whether the page, account, or runtime has ended or changed. | Stop old requests and initialize the new runtime. Do not reuse old sessions. |
| TIMEOUT | Whether the wait is for location, the Bridge, a glasses business reply, or your server. | Identify the unconfirmed step. Query actual state before deciding to retry. |
| INVALID_REQUEST | Argument types, units, ranges, and SDK/host contract. For audio, especially check old mode parameters. | Preserve the full error and check matching versions. Do not repeatedly request permissions for every failure. |
| BUFFER_OVERFLOW / QUOTA_EXCEEDED | For the former, check audio consumption speed and short-recording limits; for the latter, check file or JSON storage capacity. | Follow the relevant guide to reduce backlog or usage, retain usable data, and let the user try again. |
Reduce the issue to a minimal reproduction#
- Use one fixed ZIP and device-version combination, with the fewest actions needed to trigger the issue.
- Run the original SDK example for that capability and repeat the same actions in the same environment.
- If the original also fails, check environment, connections, and versions first. If only your project fails, compare manifests, protocols, and lifecycles.
- Change one factor at a time, rebuild, and wait for Studio packaging before testing. Do not judge changes using an old ZIP.
Copyable issue-report template#
Summary: Which side, what action, and what happened
Application: ID / version / ZIP filename
Environment: SDK version or commit, Studio version, App version
Devices: Phone model and OS, glasses model and firmware version
Time of occurrence: Date, time, and time zone
Mode: Studio simulation / App QR download / physical glasses
Prerequisites: Bluetooth, LAN, permissions, network, or demo-account requirements
Steps to reproduce:
1. Initial state
2. Button clicked or command run
3. Step at which the issue occurs
Expected result:
Actual result and complete error message:
Frequency: Every time / intermittent (occurrence count)
Does it reproduce with the unmodified SDK example?
Temporary workaround, if any:
Attachments: Redacted logs from this operation and necessary screenshotsUse stage timings to diagnose slow startup#
Distinguish first QR import from starting a saved entry. First import also includes LAN download, ZIP extraction, component validation, and saving; it cannot be compared directly with a Flash-cache-hit start.
App PluginStartup logs correlate operations by trace. lan.connect, lan.first_byte, and lan.received distinguish connection, first byte, and reception/waiting for connection closure plus SHA processing. import.download, import.decode_bundle, import.install, and import.save_* distinguish import stages. transfer.summary cache, chunks, and wireBytes confirm whether retransmission occurred.
Glasses PluginTransfer logs include write_ms, process_ms, wait_ms, and total_ms for pipelined transfer. Phone Web preparation can overlap glasses startup, and stages may nest. Do not sum every duration or treat all wall-clock waiting as CPU computation.
Reference files in the toolkit#
- GlassSDK/include/gm_plugin.h
- PhoneSDK/packages/web-sdk/src/index.d.ts
- PhoneSDK/packages/bridge-contract/src/permission-policy.js
- Studio/README.md