Errors and troubleshooting

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.