Start with these checks
- Confirm the installed package and native artifact versions.
- Test on a physical arm64 iOS device or a supported
arm64-v8aorarmeabi-v7aAndroid device. - Confirm the signed package ID, bundle identifier, or Web origin.
- Await initialization before mounting or starting the preview.
- Keep one active camera owner.
- Apply a known-good package from a readable local path.
License and initialization
| Symptom or error | Likely cause | Action |
|---|---|---|
Initialization returns false | Invalid configuration, native package mismatch, or request failure | Capture complete initialization logs and confirm the app identity and versions |
Invalid license key. Please check your license. | Key, platform, or application identity was rejected | Verify the full key privately and match the signed app identity exactly |
SDK not initialized. Please initialize the SDK first. | Preview or effect code ran too early | Await initialization and create the camera screen only after success |
| Preview is blurred and watermarked | Native verification returned INVALID | Correct the key, platform, app identity, or project configuration |
| Preview has a watermark but is not blurred | Status is UNVERIFIED | Check network reachability, wait for the final status, and retry with bounded backoff |
| Preview is blurred, watermarked, and says the license expired | Verification returned LICENSE_EXPIRED | Restore the project license, then reinitialize and verify again |
| Preview is blurred, watermarked, and says the monthly usage limit was reached | Verification returned MAU_LIMIT_EXCEEDED | Review the active plan or agreement in Console and contact the project administrator |
E_LICENSE_KEY_MISMATCH | The process was reinitialized with a different key | Keep one platform key stable for the lifetime of the process |
Do not print or send a complete production key in normal support logs.
Camera and preview
| Symptom or error | Likely cause | Action |
|---|---|---|
Camera2 error: Camera device error: 2 | Another camera session still owns the Android camera | Dispose the previous controller, force-stop during diagnosis, and open directly into Nosmai |
Camera permission is required to use this feature. Please grant permission in your device settings. | Permission was denied or restricted | Explain the need, open system settings, and retry only after access is granted |
| Black preview after navigation | Two previews exist or cleanup is incomplete | Keep one preview, await recording finalization, then dispose the previous camera screen |
| Stretched React Native Android preview | Host view uses a size or resize mode that ignores the camera aspect ratio | Give the native view measured bounds and use the package's aspect-preserving preview behaviour |
iOS reports No script URL provided | Metro is unavailable to a debug build or no JS bundle is embedded | Start Metro for Debug, or build Release with an embedded bundle |
Cannot create devtools websocket connections in embedded environments | React Native DevTools was enabled in an embedded iOS runtime | Disable the unsupported DevTools connection for that host configuration |
Filters and packages
| Symptom or error | Likely cause | Action |
|---|---|---|
| Package path is rejected | Path is missing, remote, unreadable, or contains a query or fragment | Use the unchanged result returned by a successful Cloud Filter download |
| Filter downloads but does not apply | UI used the record ID instead of cloud identifier, or ignored the returned local path | Download by cloud identifier and apply the completion result's path |
| One effect disappears after another is applied | Both packages occupy the same active slot | Follow the package replacement rules and observe active state |
Cloud Filters
| Symptom | Likely cause | Action |
|---|---|---|
| Catalog is empty | Feature is not licensed, category is wrong, or request failed | Check capability status, request all categories once, and log pagination and error details |
| Repeated downloads start | The app does not deduplicate taps | Keep one in-flight operation per cloud identifier |
| Cached filter fails offline | The app saved a stale or guessed path | Store the identifier and use the SDK's cache or listing result |
| Download stops midway | Network loss or insufficient storage | Keep the current effect, show retry, and do not apply a partial path |
Capture and recording
| Symptom | Likely cause | Action |
|---|---|---|
| Capture succeeds but saving fails | Photo-library or media permission is missing | Separate in-memory capture from gallery permission and handle save failure |
| Recording will not start | Preview is not ready, microphone access is missing, or a recording is active | Confirm ready state, request audio permission only when needed, and query recording state |
| Stop returns no file | The session was interrupted or teardown raced finalization | Stop before navigation and await the completion result |
| Android native app needs a still photo | Native Android 3.0.4 leaves still capture to the app camera | Capture through the Camera2 owner; use Flutter's higher-level method only in Flutter |
Off-screen output and streaming
| Symptom | Likely cause | Action |
|---|---|---|
| Output is delayed | Frames are queued faster than they are consumed | Process one frame and retain only the newest waiting frame |
| Output is rotated or mirrored | Orientation or mirror was applied twice | Use real pixel orientation and apply mirroring in one layer only |
| Agora remote video is black while local preview works | Android EGL share context was registered after Nosmai initialization | Create the bridge and register sharing before Nosmai creates its GL context |
| Memory grows during streaming | Pixel buffers or texture slots are not released | Release every retained buffer and stream slot, including dropped-frame paths |
What to include in a support report
- platform, device model, OS version, and ABI list
- Nosmai wrapper and native artifact versions
- app identity with secret values removed
- complete initialization result and license status
- the operation that failed and exact error after it
- whether another camera library was active
- minimal reproduction steps
Next steps
- Review license behaviour
- Check platform requirements
- Review limits and performance
- Open official samples
