# Troubleshooting

> Find the cause of license, camera, package, cloud, recording, and streaming failures by symptom and exact error.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Group: reference
Source: https://nosmai.com/docs/effects/troubleshooting/

## Start with these checks

1. Confirm the installed package and native artifact versions.
2. Test on a supported physical ARM64 device.
3. Confirm the signed package ID, bundle identifier, or Web origin.
4. Await initialization before mounting or starting the preview.
5. Keep one active camera owner.
6. 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 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

- [Review license behaviour](/docs/effects/license-key/)
- [Check platform requirements](/docs/effects/platform-support/)
- [Review limits and performance](/docs/effects/limits-and-performance/)
- [Open official samples](/docs/effects/samples/)

## References

- [Nosmai Console](https://console.nosmai.com/)
- [Android releases](https://github.com/nosmai/nosmai_effects_sdk_android/releases/latest)
- [iOS releases](https://github.com/nosmai/nosmai_effects_sdk_ios/releases/latest)