Troubleshooting your App

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:

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 adb Logcat command-line tool can be used with the Unity Extension to file logs of systems messages from Unity, Vuforia Engine, and native exception errors. Call the following expression in a terminal while an Android device is connected and running your Vuforia application.

1
Copy
adb logcat 'AndroidRuntime:V AR:V Unity:V *:F'
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

123456789101112
Copy
void 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:

  1. In an empty project with only Vuforia Engine and other assets added gradually.
  2. 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.

123
Copy
aaptOptions { 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.

Can this page be better?
Share your feedback via our issue tracker