Troubleshooting

Start from a local model file and one known image. Once that works, add optional analysis, tracking, a camera and hardware-specific preprocessing one step at a time. This keeps a loader error from becoming mixed up with an input-format problem.

Identify the loaded SDK

The current PyPI package includes these diagnostics:

import inspireface as isf

print("Python package:", isf.__version__)
print("Native SDK:", isf.version())
print("C API level:", isf.c_api_level())
print(isf.diagnostic_info())

Check both the Python package version and the native SDK version. If INSPIREFACE_LIBRARY_PATH is set, also record that path: it selects the native library in place of the one bundled with the wheel.

For the 1.2.4.post3 PyPI package, the native version is 1.2.4 and C API level is 2. Upgrade an older installation with python -m pip install --upgrade inspireface. If an old library is still selected through INSPIREFACE_LIBRARY_PATH, remove that override to use the bundled CPU library, or update the custom library as well. Restart the Python process after either change.

Library import or loading fails

On Linux, ldd /path/to/libInspireFace.so shows dynamic dependencies. On macOS, use otool -L /path/to/libInspireFace.dylib.

Set INSPIREFACE_LIBRARY_PATH before the first import. After changing the path, restart the process to load the selected library.

Windows Python loading errors

The PyPI CPU package includes a Windows x64 DLL from 1.2.4.post2 onward. Install with python -m pip install inspireface opencv-python; no SDK compilation or GPU runtime is needed for the published CPU wheel.

To inspect the interpreter and return to the bundled CPU library, run in PowerShell:

python -c "import platform, struct, sys; print(sys.executable); print(platform.machine()); print(8 * struct.calcsize('P'))"
python -m pip show inspireface
Remove-Item Env:INSPIREFACE_LIBRARY_PATH -ErrorAction SilentlyContinue
python -c "import inspireface as isf; print(isf.__version__); print(isf.version()); print(isf.c_api_level())"

The architecture should be AMD64 or x86_64, with 64 pointer bits. Start a new Python process or restart the notebook kernel after changing libraries. For a local build, Python packaging shows how to select the DLL and inspect its dependencies.

Python accepts a Windows model path such as C:/models/Pikachu or r"C:\models\Pikachu". Pass the resource-pack file to launch, not its parent folder.

Java library or buffer errors

Native methods return the C status code; InspireFaceException.check(status) throws on failure and keeps the numeric code in getCode(). Log both the code and message. JNI argument validation can also throw IllegalArgumentException before a native call. See Java integration and Java packaging.

Android 1.2.4.post1 upgrade and packaging

Session, ImageStream, FaceCapture and FaceDetectionSnapshot support explicit close. Stop workers, close capture and frame resources, then close the session. See Android lifetimes for copied facade results versus borrowed Native views.

High CPU use between frames

First confirm that the application has stopped submitting frames and that camera workers or queues are not still looping. Current CPU inference defaults to NORMAL. If the app explicitly selected HIGH, switch to NORMAL before creating sessions, close old sessions and create new ones, then compare idle CPU, frame time and temperature.

CPUEngine does not reconfigure an initialized runtime or change model thread counts and precision. See CPU policy for the Java, Android and C++ calls.

Apple framework or camera integration fails

Use the iOS and macOS guides for linkage settings. The Apple API guide includes complete NSError / Swift throws examples. Preserve the error domain, numeric code and message when logging a failure.

Model launch fails

If the model download is a ZIP archive, extract it and pass the resource-pack file to the SDK. Check the file size and checksum against the download.

Then check the pack/backend pair: Megatron_TRT needs the TensorRT build; a Gundam_* pack needs the corresponding Rockchip target. On a current build, validate_resource_pack(path) can separate resource-format problems from later session initialization problems.

Load the model once at startup. If loading fails, record the error and correct the resource or environment before creating sessions.

Detection returns no faces

“No face” is a successful processing result with an empty list or zero count. Check a clear upright face image first, then compare these settings:

• Pixel format: a BGR buffer labeled RGB can still look like a valid array but contain the wrong channel order.
• Rotation: avoid rotating the pixels and applying the same correction again in the SDK.
• Input storage: tightly packed rows, valid dimensions and a live buffer throughout processing.
• Face size: a distant face may need a higher supported detector level; minimum-face-size filtering can remove a detection.
• Mode: use ALWAYS_DETECT for unrelated still images and a tracking mode for an ordered video sequence.

Save the exact buffer submitted to the SDK as an image. Compare its colors and orientation with the camera preview, and check for padding between rows.

Boxes or landmarks drift over the preview

Check the raw-frame to display transform. Preview center-cropping, scaling, rotation and front-camera mirroring all affect the overlay. Test a face at the center and near each edge. See coordinates.

Pipeline output is missing or unchanged

Enable the desired option at session creation and request it during pipeline processing. After the call succeeds, read the results for the enabled options.

Use tokens from the matching frame and keep the image available. In C, ordinary tracking results and some getter arrays are borrowed buffers; copy them before later calls overwrite them. Ownership rules and the C guide describe each case.

Recognition or search results look wrong

Require the intended face at enrollment, use compatible embeddings from the same model, and check matched before reading a search identity. An eager search can return the first qualifying match rather than the nearest one. Use exhaustive search when the nearest qualifying entry matters.

Use a cosine-similarity threshold for recognition. Detection confidence, liveness confidence and capture scores each have their own criteria. See recognition and FeatureHub for threshold selection and model migration.

Capture never becomes ready

Feed new frames with increasing IDs and millisecond timestamps. Inspect reject_reasons and metrics.available_filters. Check that the session can detect more than one face when the face-count filter matters, and that pose/quality filters have their required session options enabled.

If you pass snapshots, create one from each new frame so the tracker count advances with the video. Use the clip's timestamps when processing an offline video.

Memory or latency grows over time

Reuse sessions, release streams and owned snapshots, and keep only the candidate images you need. Avoid unbounded frame queues and storing every embedding or preview bitmap by default. Stop submissions before releasing a worker's session.

When measuring memory, distinguish a stable allocator/runtime cache from a count of unreleased handles. The current Python API exposes show_system_resource_statistics() for the SDK's resource counters. Compare the counts after repeated create/use/release cycles.

Where can I follow the latest SDK updates?

If you need faster issue follow-up and SDK updates, follow the develop repository.

Share a reproducible issue

Include the native version, wrapper version, model identity, platform/backend, exact error code and the smallest input or code sample that reproduces the problem. For a camera issue, include the submitted format, dimensions, strides and rotation, along with a shareable test image.

Report all issues in InspireFace Issues.