Errors and troubleshooting · Nosmai Effects Docs

Error types

The SDK reports failures as typed errors. Each one carries a type, a human-readable message, and whether it is recoverable. Handle them by type.

// Flutter
try {
  await Nosmai.startRecording();
} on NosmaiError catch (e) {
  // e.type (NosmaiErrorType), e.userMessage, e.isRecoverable
}
// or listen continuously
nosmai.onError.listen((e) { /* e.type, e.userMessage */ });

// iOS: errors arrive as NSError in NosmaiErrorDomain (see codes below), and a
// notification is posted for global handling.
[[NSNotificationCenter defaultCenter] addObserver:self
    selector:@selector(onNosmaiError:) name:@"NosmaiErrorNotification" object:nil];

// Android: callbacks report a message on failure.
NosmaiEffects.applyEffect(path, new NosmaiEffects.EffectCallback() {
    @Override public void onSuccess() {}
    @Override public void onError(String message) { /* handle */ }
});

Group	Type	Meaning
General	`unknown`	Unspecified error.
General	`stateError`	Called in the wrong state (for example before initialize).
General	`operationTimeout`	The operation timed out.
General	`platformError`	A native platform error.
General	`networkError`	Network failed (license check or cloud filter).
General	`invalidParameter`	A parameter was out of range or invalid.
Initialization	`sdkNotInitialized`	Used before `initialize` succeeded.
Initialization	`invalidLicense`	License key is wrong, revoked, or not for this app.
Initialization	`licenseExpired`	The license or subscription has expired.
Camera	`cameraPermissionDenied`	Camera permission was not granted.
Camera	`cameraUnavailable`	No usable camera, or it is in use elsewhere.
Camera	`cameraConfigurationFailed`	The camera could not be configured.
Camera	`cameraSwitchFailed`	Switching front / back camera failed.
Filter	`filterNotFound`	The `.nosmai` file or id was not found.
Filter	`filterInvalidFormat`	The file is not a valid `.nosmai`.
Filter	`filterLoadFailed`	The filter failed to load.
Filter	`filterDownloadFailed`	A cloud filter download failed.
Recording	`recordingPermissionDenied`	Microphone or storage permission not granted.
Recording	`recordingStorageFull`	Not enough storage to record.
Recording	`recordingWriteFailed`	Writing the video file failed.
Recording	`recordingInProgress`	A recording is already running.

Native error codes

On iOS and Android, native errors use an NSError in NosmaiErrorDomain with one of these codes (useful when you switch on the integer code directly):

Code	Name	Meaning
1000	Unknown	Unspecified error.
1001	LicenseInvalid	License key is wrong, revoked, or not for this app.
1002	LicenseExpired	The license or subscription has expired.
1003	NetworkError	Network failed (license check or cloud filter).
1004	CameraPermissionDenied	Camera permission was not granted.
1005	CameraNotAvailable	No usable camera.
1006	EffectLoadFailed	A filter or effect failed to load.
1007	InitializationFailed	The engine failed to initialize.
1008	ResourceNotFound	A required resource was not found.
1009	InvalidParameter	A parameter was invalid.
1010	MemoryError	Out of memory.
403	FeatureNotEnabled	The feature is not enabled for this license.

License error codes

The license key is verified online on the first launch. When the licensing service rejects the request, it returns one of these codes. A wrong key or license problem must be fixed; TOO_MANY_REQUESTS, INTERNAL and NETWORK are transient, so retry with backoff.

Code	Meaning
`API_KEY_INVALID`	Key not found, wrong, or revoked.
`LICENSE_EXPIRED`	The license or subscription has expired.
`PACKAGE_ID_MISMATCH`	The key is for a different app (package name / bundle id).
`PLATFORM_MISMATCH`	The key is for a different platform.
`SDK_VERSION_UNSUPPORTED`	This SDK version is not allowed.
`MAU_LIMIT_EXCEEDED`	The monthly active user / device limit was reached.
`DEVICE_NOT_REGISTERED`	The device is not registered for this key.
`TIMESTAMP_INVALID`	The device clock is too far off. Fix the device time.
`TOO_MANY_REQUESTS`	Rate limited. Retry with backoff.
`MISSING_FIELDS`	A required field is missing from the request.
`INTERNAL`	A server error. Retry later.
`NETWORK`	The device could not reach the licensing service.

Get and manage keys from the portal.

Permissions

Black or frozen preview. Confirm the camera permission is granted, and request it before starting the camera.
Recording fails. Add the microphone permission, plus the photo library permission if you save to the gallery.

Performance

Low frame rate. Test on a physical device, not an emulator or simulator. On lower-end devices, reduce the number of simultaneous effects.
Heat or battery drain in long sessions. The SDK adapts quality automatically; avoid stacking many heavy effects at once, and stop processing when the camera is not visible.

Filters

Filter does not load (filterNotFound / filterLoadFailed). For local filters, confirm the .nosmai files are bundled correctly: a folder reference in the iOS app target, or assets/filters/ on Android and Flutter.
Cloud filter unavailable (filterDownloadFailed). Check that cloud filters are enabled for your license, and download a filter before applying it.

Lifecycle

Preview is blank after navigating back (Flutter). Detach the camera view before leaving the screen and reinitialize the preview when returning.
Resources not released (Android). Call stopProcessing and the cleanup methods in onPause and onDestroy, and stop the camera helper.

Platform notes

iOS. Run on a physical device. The simulator does not provide a camera feed.
Android. Requires a physical arm64 device with Camera2 support.