Support
Troubleshooting
Diagnose common SDK setup, identity, Portal, and notification issues with stable error codes and request IDs.
Common Error Codes
| Code | Usually means | Fix |
|---|---|---|
| invalid_sdk_key | The SDK key is missing or does not match the hosted project configuration. | Copy the SDK initialization key from Settings -> Integrations and confirm the app uses the target project. |
| project_not_found | The project ID, slug, or portal subdomain could not be resolved. | Use the project ID shown in the dashboard, or verify the Portal slug/subdomain. |
| portalNotReady | The SDK has not resolved the Portal descriptor yet. | Call try await Gleam.shared.start() before presenting Portal UI or building Portal URLs. |
| identity_not_configured | Signed identity is not configured for this project on the server. | Configure the project identity secret server-side before calling identify(signedIdentityToken:). |
| unauthorized | An authenticated endpoint was called without a valid session token. | Run start() or identify(signedIdentityToken:) before calling authenticated APIs. |
Diagnostics In Swift
In debug builds, enable SDK logs and catch GleamError.server so you can report the stable code and requestId.
Error handling
#if DEBUG
Gleam.shared.setLogLevel(.debug)
#endif
do {
try await Gleam.shared.start()
} catch GleamError.server(let code, let message, let statusCode, let requestId) {
print("Gleam SDK error \(code) \(statusCode): \(message)")
print("requestId: \(requestId ?? "-")")
} catch GleamError.portalNotReady {
print("Call start() before presenting Portal UI.")
} catch {
print("Gleam SDK failed: \(error)")
}Fast Checklist
- Confirm the app is using a client-safe SDK key, not a server-only secret.
- Confirm NEXT_PUBLIC_SITE_URL and Portal routing resolve to the expected hosted environment.
- Confirm signed identity tokens use HS256, include sub and exp, and are not generated in client code.
- Confirm APNs token registration only runs after the SDK has an authenticated session.
- Include requestId and the SDK log line when asking for support.