Use this guide to narrow down, identify root causes, and fix bugs and common issues you might experience while developing an app with the Vuforia Engine SDK.
If none of the information on this page helps resolve your issue, and you are confident there might be a problem with Vuforia Engine SDK, please file a bug report using the GitHub issue tracker.
Content:
Preliminary Checklist
Check the platform compatibility
Vuforia Engine SDK supports app development targeting iOS, Android, Windows UWP (HoloLens, PC, and tablets), and Magic Leap OS. The minimum OS-supported versions are listed on the Supported Versions page. Please note that Win32 (non-UWP) application development is currently not supported.
Check the development tool's compatibility
Check your development tools against the Vuforia Engine Supported Versions. In particular, check:
- Unity version (Unity development).
- Xcode version (iOS development).
- Android Studio, SDK, NDK, Gradle versions (Android development).
- Visual Studio version (Windows UWP development).
Check the feature support
Check that your target or test platform supports the Vuforia Engine feature you are using. This table includes per-feature platform-specific requirements. Also, note that the behavior of some features (e.g., Ground Plane) might differ across platforms.
Check your device
Check if the devices you are targeting for your app are part of the Recommended Devices list. These are devices actively tested by the Vuforia Engine development team. While Vuforia Engine SDK works on many more devices, it is good practice to reproduce your problem on a recommended device. Also:
- Check that the device OS is up to date.
- Ensure that the device supports the Vuforia Engine feature you are using. For example, Area Targets requires that the device has ARCore or ARKit enabled.
- For Android devices, check that Google Play Services for AR (i.e., ARCore) is also up-to-date.
Check your target
Check that your target fulfills the expected guidelines and best practices recommended for the specific target type. Relevant information is available at the following links:
- Model Targets: best practices
- Area Targets: best practices for scanning a space.
- Image Targets: best practices, physical properties, and Image Optimization techniques.
- Cylinder Targets: best practices.
- Multi Targets: best practices.
- VuMarks: design guide.
- Barcodes: best practices.
Check your license
Check that you have an active and valid license key in your app project. A valid license key ensures all features of Vuforia Engine will work at authoring time and runtime. See the Status of your license in the Plan & Licenses Tab. Expired and suspended licenses will result in authoring and runtime failures.
Debugging
Vuforia Engine errors and error handling
The Vuforia Engine API has error codes for a range of circumstances. These include creating and initializing the Vuforia Engine instance, creating Observers and Behaviours, Platform-Specific errors, database and target-specific errors, etc.
See Error Handling in Unity and Error Handling in Native to add error reporting to your code.
Collect Logs
All development platforms provide consoles for recording and inspecting logging messages reported by your app, the OS, and the Vuforia Engine SDK. Inspect the log to learn about specific errors and warnings.
Unity |
Set the LogLevel in Vuforia Configuration to ALL to get more Vuforia messages in Unity. See Vuforia Engine Lifecycle in Unity to set the LogLevel. See also Unity’s Log Files for getting the logs for the editor, player, and hub-related problems. |
Android |
For Android applications, the 1
|
HoloLens |
You can obtain the logs from the Event Tracing for Windows (ETW) for HoloLens applications. See the setup guide Capturing and Viewing Event Logs with ETW. |
Log handler callback
Vuforia Engine provides a native API to handle log messages programmatically. When you register a callback handler to trigger every time Vuforia Engine logs a message to the standard platform logging system. Use this, for example, to integrate Vuforia Engine logs into your own logging streams. You can see the log levels reported in the callback and extend your app to filter them accordingly. The available log levels are listed in the API reference Library.
Example implementation
123456789101112Copyvoid onNewLogEvent(VuLogEvent logEvent, void* clientData)
{
// Handle log event
}
VuLogHandlerConfig logHandlerConfig = vuLogHandlerConfigDefault();
logHandlerConfig.logHandler = &onNewLogEvent; // Pointer to handler function
ogHandlerConfig.clientData = NULL;
vuEngineConfigSetCreate(&configSet);
VuEngineConfigSet* configSet = NULL;
vuEngineConfigSetAddLogHandlerConfig(configSet, &logHandlerConfig);
Cloud Web API
See the VWS Result Codes for the HTTP status codes. If you report an issue, include the request and response's transaction_id, timestamp, and URL.
Reproduce your Issue
It is best practice to isolate and reproduce an issue in a new minimal project. This new project is also better suited to share with others.
There are two ways to do this:
- In an empty project with only Vuforia Engine and other assets added gradually.
- In a new development project with the Core Samples or Native Samples. Add then your target databases and settings to see if they work.
Follow the Get Started Guides for adding Vuforia Engine and, optionally, the Vuforia Samples to the project and test with your targets, scripts, and other assets. If the issue persists, go to Vuforia Engine Issue Tracker and make a bug report.
Troubleshooting Common Problems
The target is never observed
If your target is never detected, inspect the log for messages related to the loading and activation of the correct database containing the target.
In Unity, ensure you are not disabling the GameObject that has the <target>Behaviour component.
TIP: Refer to the Status and Status Info reported in the logs. You can learn about your target’s tracking quality from the status and status info and set your application to react when, for example, the target is lost or changed to Extended Tracked.
Augmentation floats around
If your content floats around and seems detached from the physical object, check the following:
- Check for a wrongly scaled target. The size of your target should match the size of the physical object defined in meters. An incorrect scale will result in floating augmentations. For Model Targets please review the guide on how to manage Managing Scaling.
- In Unity, check that your augmented content is a child of the target GameObject. Also, check that the augmentations have the correct transformations according to your target and are correctly scaled.
Augmentation jumps
Content rendered in a misplaced position, only to jump back to the target and its correct position, is usually caused by a longer duration of limited tracking accuracy. Vuforia Engine uses Extended Tracked and the last detected position of the target to continue to render your augmentations. The “re-snapping” to the target happens when the target is again detected and tracked.
If you experience your content being misplaced and jumping back to the target, you can use the DefaultObserverEventHandler to set Vuforia Engine not to track the target when a limited status is reported.
You can also use Pose Smoothing in the DefaultObserverEventHandler to create an animated transition for your content when it returns to its correct position.
The device screen is black
If your AR application only shows a black screen, it could indicate that Vuforia Engine cannot access the camera. Check that the camera permissions were granted.
The target never loads on my Android device
If you are developing an Android app and the target takes a long time or never loads, it may help to keep the dataset files uncompressed. Add the 3DT and DAT files to the aaptOptions
in the Build.Gradle inside the android
block.
123CopyaaptOptions {
noCompress = ['.3dt', '.dat']
}
Area Targets Troubleshooting
Area Target is not detected or takes a long time to initiate.
Check the status of device tracking while attempting to detect the Area Target. A TRACKED/NORMAL pose is a prerequisite for detecting Area Targets. On ARCore-enabled devices, more motion may be required to initialize the tracking properly.
TIP: test your Area Target with the Creator App for iOS or the Vuforia Area Targets Test App for Android. This can help distinguish between issues with your app and issues with the specific device.