Troubleshooting
Diagnose common SDK setup, identity, Portal, and notification issues with stable error codes and request IDs.
Last reviewed June 2, 2026
Common Error Codes
Start with the error code, HTTP status, and requestId. The code usually tells you which layer failed: project lookup, SDK key validation, session authentication, identity configuration, or Portal readiness.
| 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. |
Triage Order
When an SDK integration fails, check the simplest boundary first. Most issues come from using the wrong project values, presenting the Portal before start() completes, generating signed identity tokens on the wrong backend, or registering APNs before the SDK has an authenticated session.
Confirm project configuration
Copy the project ID and SDK key again from the intended Gleam dashboard project. If you use multiple environments, confirm the app is not mixing production and staging values.
Check SDK session startup
Call start() before presenting Portal UI or using authenticated APIs. Log the server error code and requestId when bootstrap fails.
Validate identity tokens
If identify(...) fails, decode the token header and payload without trusting it. Confirm alg is HS256, sub and exp exist, aud points at the intended project, and the token was signed by your backend.
Verify notification sequencing
For APNs issues, confirm notification permission, bundle ID, APNs environment, dashboard credentials, authenticated SDK session, and device token registration in that order.
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.
What To Include When Asking For Help
A good support packet should let the issue be reproduced without exposing secrets. Include identifiers and logs that point to the failing request, but redact tokens, APNs private keys, identity secrets, and user personal data.
- Gleam project ID or project slug, plus whether the app is using development, staging, or production values.
- SDK version, iOS version, app lifecycle style, and whether the failing path is SwiftUI or UIKit.
- The error code, HTTP status, requestId, and the screen or user action that triggered the request.
- Whether the user was anonymous, signed in with identity, or expected to receive APNs push.
- A short description of what you expected to happen and what happened instead.