Troubleshooting

Common integration issues and their fixes.

customEndpoints rejected

Cause: customEndpoints were passed while using production, sandbox, or staging.

Fix: Only pass customEndpoints with EixamEnvironment.custom.

initialSession.appId mismatch

Cause: The bootstrap appId and the provided signed session appId do not match.

Fix: Make both values identical.

Signing flow confusion

Cause: The mobile app is trying to hold the app secret or compute userHash locally.

Fix:

• Keep the app secret on the partner backend only
• Generate or obtain userHash on the backend for appId + externalUserId
• Pass the resulting signed session to the mobile app
• Perform all signing within the partner backend

Realtime URI looks non-WebSocket

Cause: The public field is named websocketUrl, but the configured broker may use a different transport scheme.

Fix: This is expected. Depending on environment and client transport, the broker URI may be ssl://, tls://, tcp://, ws://, or wss://.

Bootstrap did not request permissions

This is expected behavior. Permission requests remain explicit host-app actions — the SDK does not trigger them on its own.

Bootstrap did not pair a device

This is expected behavior. Device pairing and connection remain explicit host-app decisions.

Protection readiness is blocked

Inspect each of the following:

• Session availability
• Paired/connected device state
• Bluetooth enabled state
• Location permission
• Notification permission
• Platform capability readiness

iOS Protection coverage remains partial

This can be expected depending on current iOS runtime ownership support. See iOS Integration.

Realtime appears incomplete

Current realtime may depend on backend protocol maturity. Use runtime diagnostics and the agreed backend transport behavior as the source of truth.

MQTT auth fails after copying HTTP headers

Cause: MQTT auth is being treated like HTTP auth or old MQTT 5 User Properties.

Fix:

Transport	Auth
HTTP	Authorization: Bearer <userHash>
MQTT username	sdk:<appId>:<externalUserId>
MQTT password	<userHash> (no Bearer prefix)