Reference
Troubleshooting Find the cause of license, camera, package, cloud, recording, and streaming failures by symptom and exact error.
SDK version Native 3.0.4 · Flutter 1.0.2 Updated Aug 22, 2026 Time 12 min
iOS Android Flutter
Start with these checks Confirm the installed package and native artifact versions. Test on a supported physical ARM64 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_MISMATCHThe 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: 2Another 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 environmentsReact 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 an unchanged path returned by local discovery or 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 Game runs but taps do nothing Tap coordinates were not normalized to the preview content area Convert the touch point within the rendered preview to values from 0 through 1
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 References Was this page helpful? Your response helps us prioritize documentation improvements.
Thanks for the feedback.
