This topic provides troubleshooting tips for a variety of common situations known to affect Shared Spatial Anchors for the Meta Horizon OS.

You can find more information on effective use Tips for Using Spatial Anchors

Shared Spatial Anchors is available for Meta Quest Pro on v47 or higher, and Meta Quest 2 on v49 or higher. Most of the issues on this page require device logs to diagnose. Refer to Set up your environment for using adb logcat to retrieve logs.

This section lists several scenarios that you may encounter during development. It briefly explains the cause and provides the resolution to fix the issue.

The device setting Enhanced Spatial Services must be enabled for Shared Spatial Anchors to function. Users can find it under Settings > Privacy > Device Permissions > Enhanced Spatial Services.

Your app can detect when this setting is disabled and inform users to turn it on. Your app will receive the error code.

Upon sharing an SSA or saving an SSA to the cloud when this setting is disabled. Your app should check for this error and inform users that enabling Enhanced Spatial Services is required for SSA to function in your experience.

There are a couple of instances when the system cannot locate a previously stored spatial anchor:

To recover from this, you need to either:

Operations on Persisted Anchors fail indicating package is not trusted.

When accessing local or shared spatial anchors, we verify the identity of the application requesting access to persisted Spatial Anchors. Because this verification uses information registered in the Store, your application will not be able to persist or share Spatial Anchors until you register your app on dashboard.oculus.com.

If you are encountering this issue, the logs will contain the message: Package <your application’s package ID> is not trusted, status: <error code>, sessionUuid: <id>"

Client fails to download the specified anchors. Common reasons that lead to this error are:

To determine which issue you are hitting, look for the following messages in the log.

The following are common reasons why anchors may not be present in the cloud, or the user may not have access, causing the download to fail:

To resolve this issue, the sender of the anchor needs to upload and share the anchor again by following these steps:

The Spatial Anchors are failing to upload. Search for the following messages to identify the mode of failure: xr_cloud_anchor_service: Number of anchors uploaded did not match number of anchors returned and xr_cloud_anchor_service: Failed to upload spatial anchor with error <error>. The error messages indicate that the upload of Spatial Anchors to the cloud has failed. A common reason is that an internal service issue is encountered, such as resource limits or the endpoint being unavailable.

Check the actual error description for details on why the operation failed. If the error description indicates an issue with the Spatial Anchor itself, try creating and uploading a new Spatial Anchor.

Sharing Spatial Anchors with other users fails. This can be due to a few reasons:

The first step to debugging issues with sharing is to check the result codes returned by the Share() functions. See below for possible causes and mitigations for several common error conditions.

To further diagnose this issue, search for the following message in logs: xr_cloud_anchor_service: Failed to share spatial anchor with error <error from cloud>.

The Shared Anchor is not in the same place on the sender and recipient’s devices.

During testing, you may find that the Spatial Anchor that was shared is not in the expected position on the recipient’s device. This can happen if the system does not correctly localize the Shared Anchor.

For the best experience, we recommend that users enter Passthrough and walk around in a large circle (while communicating with and staying mindful of the location of others) around the center of their playspace before using experiences that use Shared Spatial Anchors. Optionally, you may communicate to the user to walk and look around the playspace. If the anchor’s pose does not automatically correct, you can destroy the anchor and download it again.

You encounter

when attempting to save, load, or share Spatial Anchors

When attempting to upload, download, or share Spatial Anchors, you may receive error “cloud sotrage disabled”. Additionally, the logs will contain one or more of the following:

Some known causes are:

The user must take action to grant permissions to Enhanced Spatial Services for this feature to work. You can surface a prompt to indicate to the user to enable this permission from Settings > Privacy.

You encounter XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB when attempting to save, upload, or share an anchor.

You are attempting the operation for an anchor that does not have the required components enabled. This could be because you are attempting to save, upload, or share a Scene Anchor, which is managed by the Meta Quest operating system.

Make sure every anchor you are attempting to save or share is a Spatial Anchor (not a Scene Anchor). In Unity and Unreal, the class of the object you are using will indicate whether it is a Spatial Anchor.

If you are using the OpenXR API, use the following code to check for component status before saving or uploading an anchor, given an XrSpace:

XrSpaceComponentStatusFB storableStatus;
xrGetSpaceComponentStatusFB(
    space, XR_SPACE_COMPONENT_TYPE_STORABLE_FB, &storableStatus));
if (storableStatus.enabled) {
    // Save or upload the anchor.
}

Use the following code to check for component status before sharing an anchor, given an XrSpace:

XrSpaceComponentStatusFB sharableStatus;
xrGetSpaceComponentStatusFB(
    space, XR_SPACE_COMPONENT_TYPE_SHARABLE_FB, &sharableStatus));
if (sharableStatus.enabled) {
    // Share the anchor.
}

You encounter

when attempting to save, load, or share an anchor.

This error occurs when the device’s maping of the current physical surroundings is not complete enough to reliably save or load a SSA.

Prompting users to look around the room to ensure the device has fully mapped the space and then retrying the operation that led to this failure.

You encounter

when attempting to save, load, or share an anchor.

This error occurs when anchors are successfully loaded from the cloud, but cannot be aligned with the device’s map of its physical surroundings.

This error typically occurs when there is poor coordination between the user that has saved and shared the SSA and the user attempting to load the SSA. (i.e. the host user asks a guest user to load an anchor that is not located in their current space)

A possible mitigation is to prompt users to look around the room to ensure the device has fully mapped the space and then retrying the operation that led to this failure.

You encounter

when attempting to save, load, or share an anchor.

This error occurs when there is failure to complete cloud-based saves and loads due to a network timeout.

Retrying the operation is the first step to mitigating this error. It may also be appropriate to alert the user that their network connection is too slow to reliably load, save, or share SSAs and limit this functionality within your app if the issue persists.

You encounter

when attempting to save, upload, or share an anchor.

This error occurs when there is failure to complete cloud-based saves and loads for reasons other than a network timeout.

It is probable that the device has lost internet connectivity if you app receives this error. It may be appropriate to alert the user that their network connection is unreliable and/or to retry the attempted operation.

Continue learning about spatial anchors by reading these pages: