Error Handling

Return Value Convention

Most SDK methods return int:

Return value	Meaning
`0`	Success
Non-zero	Failure — check the log output for details

BeautyEffectEngine::Create() returns a std::shared_ptr; it returns nullptr on failure.

Common Errors and Fixes

1. Engine Creation Fails (`Create` Returns `nullptr`)

Possible causes:

Invalid or inactive app_id / app_key
resource.fbd file not found at resource_path
facebetter.dll missing or version mismatch
No network access (online authentication failed)

How to diagnose:

// Enable logging BEFORE calling Create
LogConfig log_cfg;
log_cfg.console_enabled = true;
log_cfg.level           = LogLevel::Debug;
BeautyEffectEngine::SetLogConfig(log_cfg);

auto engine = BeautyEffectEngine::Create(eng_cfg);
if (!engine) {
    std::cerr << "[Error] Engine creation failed. Check log output." << std::endl;
    return -1;
}

Common fixes:

Use an absolute path to rule out relative path issues:

#include <filesystem>
eng_cfg.resource_path =
    (std::filesystem::current_path() / "resource" / "resource.fbd").string();

Make sure facebetter.dll is in the same directory as the executable (CMake copies it automatically after build).
Get fresh app_id and app_key from the dashboard.

2. `facebetter.dll` Not Found at Runtime

Symptom: A Windows dialog reports “facebetter.dll was not found” on startup. Fix:

:: Check whether the DLL is next to the executable
dir build\facebetter.dll

:: If missing, copy manually
copy sdk\lib\facebetter.dll build\

Or re-run cmake --build build — CMake automatically copies the DLL after every build.

3. `ProcessImage` Returns `nullptr`

Possible causes:

Input ImageFrame is null (file not found, unsupported format, etc.)
Engine was not initialized successfully
Out of memory

How to handle:

auto input = ImageFrame::CreateWithFile("input.jpg");
if (!input || !input->Data()) {
    std::cerr << "[Error] Failed to load input image." << std::endl;
    return;
}

auto output = engine->ProcessImage(input);
if (!output || !output->Data()) {
    std::cerr << "[Error] ProcessImage failed." << std::endl;
    return;
}

4. Beauty Effects Have No Visible Impact

Possible causes:

The relevant BeautyType was not enabled via SetBeautyTypeEnabled
Parameter value is 0 (effect is off)
No face detected in the frame (reshape/makeup require face detection to succeed)

Checklist:

// Enable each type you need
engine->SetBeautyTypeEnabled(BeautyType::Basic,   true);
engine->SetBeautyTypeEnabled(BeautyType::Reshape, true);
engine->SetBeautyTypeEnabled(BeautyType::Makeup,  true);
engine->SetBeautyTypeEnabled(BeautyType::Sticker, true);

// Ensure the parameter value is greater than 0
engine->SetBeautyParam(Basic::Smoothing, 0.5f);  // 0 = disabled

5. `SetBeautyParam` Returns Non-Zero

Possible causes:

engine is nullptr (engine creation failed earlier)
Value out of range [0.0, 1.0]

How to handle:

int ret = engine->SetBeautyParam(Basic::Smoothing, 0.5f);
if (ret != 0) {
    std::cerr << "[Error] SetBeautyParam failed, code: " << ret << std::endl;
}

6. OpenGL / Display Issues

Possible causes:

GLFW initialization failed (driver issue or OpenGL 3.0+ not available)
gladLoadGLLoader returned false

How to diagnose:

if (!glfwInit()) {
    std::cerr << "[Error] GLFW init failed." << std::endl;
    return 1;
}
glfwWindowHint(GLFW_CONTEXT_VERSION_MAJOR, 3);
glfwWindowHint(GLFW_CONTEXT_VERSION_MINOR, 0);

Make sure your GPU driver is up to date. Hardware OpenGL is usually unavailable in virtual machines or Remote Desktop sessions.

Enabling Debug Logs

During development, enable Debug-level logging for maximum detail:

LogConfig log_cfg;
log_cfg.console_enabled = true;
log_cfg.file_enabled    = true;
log_cfg.level           = LogLevel::Debug;
log_cfg.file_name       = "facebetter.log";
BeautyEffectEngine::SetLogConfig(log_cfg);

The log file is written to the same directory as the executable.

Error Code Reference

Code	Meaning
`0`	Success
`-1`	Engine not initialized
`-2`	Invalid parameter
`-3`	Resource file not found
`-4`	Processing failed

Introduction

Android

iOS

macOS

Windows

Linux

Web

Flutter

Return Value Convention

Common Errors and Fixes

1. Engine Creation Fails (`Create` Returns `nullptr`)

2. `facebetter.dll` Not Found at Runtime

3. `ProcessImage` Returns `nullptr`

4. Beauty Effects Have No Visible Impact

5. `SetBeautyParam` Returns Non-Zero

6. OpenGL / Display Issues

Enabling Debug Logs

Error Code Reference

​Return Value Convention

​Common Errors and Fixes

​1. Engine Creation Fails (Create Returns nullptr)

​2. facebetter.dll Not Found at Runtime

​3. ProcessImage Returns nullptr

​4. Beauty Effects Have No Visible Impact

​5. SetBeautyParam Returns Non-Zero

​6. OpenGL / Display Issues

​Enabling Debug Logs

​Error Code Reference

Return Value Convention

Common Errors and Fixes

1. Engine Creation Fails (`Create` Returns `nullptr`)

2. `facebetter.dll` Not Found at Runtime

3. `ProcessImage` Returns `nullptr`

4. Beauty Effects Have No Visible Impact

5. `SetBeautyParam` Returns Non-Zero

6. OpenGL / Display Issues

Enabling Debug Logs

Error Code Reference