Error Handling

This page matches SDK 2.0.0. Auth: Auth & License.

Error codes (`FBErrorCode`)

Setter APIs return int. 0 is success. createEngineWithConfig: and processImage: return objects (nil on failure).

Value	Symbol	Meaning
`0`	`FBErrorCode_Success`	Success
`-1`	`FBErrorCode_InvalidArgument`	Invalid argument (nil config, empty path, out-of-range value, …)
`-2`	`FBErrorCode_NotInitialized`	Engine is not initialized
`-3`	`FBErrorCode_License`	License / auth failure
`-4`	`FBErrorCode_Unsupported`	Unsupported format, platform, or feature
`-5`	`FBErrorCode_IO`	File / resource I/O error
`-6`	`FBErrorCode_NoSlot`	No available slot (for example too many faces)
`-7`	`FBErrorCode_Process`	Frame processing failed
`-8`	`FBErrorCode_OutOfMemory`	Out of memory

typedef NS_ENUM(NSInteger, FBErrorCode) {
  FBErrorCode_Success = 0,
  FBErrorCode_InvalidArgument = -1,
  FBErrorCode_NotInitialized = -2,
  FBErrorCode_License = -3,
  FBErrorCode_Unsupported = -4,
  FBErrorCode_IO = -5,
  FBErrorCode_NoSlot = -6,
  FBErrorCode_Process = -7,
  FBErrorCode_OutOfMemory = -8,
};

Check return values

FBLogConfig *logConfig = [[FBLogConfig alloc] init];
logConfig.consoleEnabled = YES;
logConfig.level = FBLogLevel_Info;
int logRet = [FBBeautyEffectEngine setLogConfig:logConfig];
if (logRet != FBErrorCode_Success) {
  NSLog(@"setLogConfig failed: %d", logRet);
}

FBEngineConfig *config = [[FBEngineConfig alloc] init];
config.appId = @"your_app_id";
config.appKey = @"your_app_key";
self.engine = [FBBeautyEffectEngine createEngineWithConfig:config];
if (self.engine == nil) {
  NSLog(@"Failed to create engine (check license, Bundle ID, network, and logs)");
  return;
}

int ret = [self.engine setSmoothing:0.5f];
if (ret != FBErrorCode_Success) {
  NSLog(@"setSmoothing failed: %d", ret);
}

Map codes in one place:

NSString *FBErrorMessage(int code) {
  switch (code) {
    case FBErrorCode_Success: return @"success";
    case FBErrorCode_InvalidArgument: return @"invalid argument";
    case FBErrorCode_NotInitialized: return @"engine not initialized";
    case FBErrorCode_License: return @"license / auth failure";
    case FBErrorCode_Unsupported: return @"unsupported";
    case FBErrorCode_IO: return @"I/O error";
    case FBErrorCode_NoSlot: return @"no available slot";
    case FBErrorCode_Process: return @"process failed";
    case FBErrorCode_OutOfMemory: return @"out of memory";
    default: return [NSString stringWithFormat:@"unknown (%d)", code];
  }
}

Engine events

FBEngineCallbacks.onEngineEvent reports license and init asynchronously. Set callbacks immediately after creating the engine.

Code	Symbol	Meaning
`0`	`FBEngineEventCodeLicenseValidationSuccess`	License OK
`1`	`FBEngineEventCodeLicenseValidationFailed`	License fail
`100`	`FBEngineEventCodeInitializationComplete`	Init complete
`101`	`FBEngineEventCodeInitializationFailed`	Init fail

FBEngineCallbacks *callbacks = [[FBEngineCallbacks alloc] init];
callbacks.onEngineEvent = ^(FBEngineEventCode code, NSString * _Nullable message) {
  switch (code) {
    case FBEngineEventCodeLicenseValidationFailed:
      NSLog(@"License failed: %@", message);
      break;
    case FBEngineEventCodeInitializationFailed:
      NSLog(@"Init failed: %@", message);
      break;
    default:
      break;
  }
};
[self.engine setCallbacks:callbacks];

createEngineWithConfig: returning a non-nil instance does not replace listening for event 1 / 101. Online auth can still fail after construction.

Image processing

Validate the frame, set type, and treat a nil return as FBErrorCode_Process. macOS can handle larger stills; still reject zero-size buffers.

- (FBImageFrame *)processSafely:(FBImageFrame *)input {
  if (input == nil || input.width <= 0 || input.height <= 0) {
    NSLog(@"Invalid FBImageFrame");
    return nil;
  }
  input.type = FBFrameTypeVideo;
  FBImageFrame *output = [self.engine processImage:input];
  if (output == nil) {
    NSLog(@"processImage returned nil");
  }
  return output;
}

Save with toFile: (returns FBErrorCode):

int saved = [output toFile:path quality:90];
if (saved != FBErrorCode_Success) {
  NSLog(@"toFile failed: %d", saved);
}

createWithNSImage: returns nil if the NSImage has no bitmap representation.

Logging

Enable logs before creating the engine. Create the log directory if you write a file. In a sandboxed Mac app, write under the container (for example Application Support), not an arbitrary path.

NSString *logPath = [NSTemporaryDirectory() stringByAppendingPathComponent:@"facebetter.log"];
NSString *logDir = [logPath stringByDeletingLastPathComponent];
[[NSFileManager defaultManager] createDirectoryAtPath:logDir
                          withIntermediateDirectories:YES
                                           attributes:nil
                                                error:nil];

FBLogConfig *logConfig = [[FBLogConfig alloc] init];
logConfig.consoleEnabled = YES;
logConfig.fileEnabled = YES;
logConfig.level = FBLogLevel_Debug;
logConfig.fileName = logPath;
[FBBeautyEffectEngine setLogConfig:logConfig];

macOS-specific failures

App Sandbox: enable outgoing network for online appId / appKey. User-selected files need security-scoped bookmarks (startAccessingSecurityScopedResource).
-5 I/O: the .fbd / background image is outside the sandbox or the bookmark is not started.
CLI tools: if there is no Bundle ID, bind the process name in the Dashboard.
External GL: if externalContext = YES, create and process on the same OpenGL thread.

Practical checks

-1 Invalid argument: empty .fbd path, nil NSData, intensity outside the documented range, or a nil config.
-2 Not initialized: calling setters after a failed createEngineWithConfig: (the instance is nil).
-3 License: wrong credentials, unbound Bundle ID, expired token, or sandbox blocking the auth request. See Auth & License.

Introduction

Android

iOS

macOS

Windows

Linux

Web

Error codes (`FBErrorCode`)

Check return values

Engine events

Image processing

Logging

macOS-specific failures

Practical checks

​Error codes (FBErrorCode)

​Check return values

​Engine events

​Image processing

​Logging

​macOS-specific failures

​Practical checks

Error codes (`FBErrorCode`)

Check return values

Engine events

Image processing

Logging

macOS-specific failures

Practical checks