Restoring persistent anchors is not supported in this enviro

Error message

Restoring persistent anchors is not supported in this environment/browser

What it means

After confirming the anchor system is attached, restorePersistentAnchorAsync checks that the session exposes restorePersistentAnchor. That native method belongs to the optional persistent anchors extension; when the session does not implement it, the method throws this capability error so callers know restoration is impossible in this environment rather than failing obscurely later.

Source

Thrown at packages/dev/core/src/XR/features/WebXRAnchorSystem.pure.ts:337

        this._setPersistentHandle(anchor, handle);
        return handle;
    }

    /**
     * Restore a persistent anchor into the Babylon anchor lifecycle
     * @param handle The persistent anchor handle to restore
     * @returns A promise that resolves after the restored anchor is tracked by an XR frame
     * @throws If restoring persistent anchors is not supported by the current session
     */
    public async restorePersistentAnchorAsync(handle: string): Promise<IWebXRAnchor> {
        if (!this.attached) {
            throw new Error("Restoring persistent anchors requires the anchor system to be attached");
        }

        const session = this._xrSessionManager.session;
        const restorePersistentAnchor = session?.restorePersistentAnchor;
        if (!restorePersistentAnchor) {
            throw new Error("Restoring persistent anchors is not supported in this environment/browser");
        }

        const nativeAnchor = await restorePersistentAnchor.call(session, handle);
        if (!this.attached || this._xrSessionManager.session !== session) {
            nativeAnchor.delete();
            throw new Error("Persistent anchor restoration was interrupted before tracking began");
        }
        const existingAnchorIndex = this._findIndexInAnchorArray(nativeAnchor);
        if (existingAnchorIndex !== -1) {
            const existingAnchor = this._trackedAnchors[existingAnchorIndex];
            existingAnchor.persistentHandle = handle;
            return existingAnchor;
        }

        return await new Promise<IWebXRAnchor>((resolve, reject) => {
            this._futureAnchors.push({
                nativeAnchor,
                resolved: false,

View on GitHub (pinned to 0592b347b8)

Solutions

Negotiate the persistent anchors feature when creating the session
Feature-detect session.restorePersistentAnchor before calling restore
Skip persistence features gracefully on unsupported devices
Update browser/headset runtime to a version with restorePersistentAnchor

Example fix

// before
const anchor = await anchorSystem.restorePersistentAnchorAsync(handle);
// after
const session = xrSessionManager.session;
if (session && typeof session.restorePersistentAnchor === 'function') {
  const anchor = await anchorSystem.restorePersistentAnchorAsync(handle);
} else {
  console.warn('persistent anchor restore unsupported');
}

Defensive patterns

Strategy: type-guard

Validate before calling

const session = xrSessionManager.session;
const restorable = !!session && typeof (session as any).restorePersistentAnchor === 'function';

Type guard

function supportsRestore(session: XRSession | undefined): session is XRSession & { restorePersistentAnchor(h: string): Promise<XRAnchor> } {
  return !!session && 'restorePersistentAnchor' in session;
}

Try / catch

try {
  await anchorSystem.restorePersistentAnchorAsync(handle);
} catch {
  console.warn('restore unsupported here; dropping persistence for this handle');
}

Prevention

Negotiate the persistence feature during session creation
Feature-detect session.restorePersistentAnchor before restoring
Provide a non-persistent fallback for anchors
Update runtimes that lack restorePersistentAnchor

When it happens

Trigger: Calling restorePersistentAnchorAsync(handle) when this._xrSessionManager.session.restorePersistentAnchor is undefined — browsers/devices with anchors but no persistence API, or a session created without persistence support.

Common situations: Runtimes implementing anchors transiently only, missing feature negotiation in requiredFeatures/optionalFeatures, older browser versions or emulators.

Related errors

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/cece4d52ec79b48c. Report an issue: GitHub.