Requesting persistent anchor handles is not supported in thi

Error message

Requesting persistent anchor handles is not supported in this environment/browser

What it means

requestPersistentHandleAsync asks the native XRAnchor for a persistent handle. Native anchors only expose requestPersistentHandle in environments supporting anchor persistence; when the method is missing on the anchor object, the method throws immediately rather than calling an undefined function. This signals the runtime cannot persist this anchor.

Source

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

     */
    public get persistentAnchors(): ReadonlyArray<string> {
        const persistentAnchors = this._xrSessionManager.session?.persistentAnchors;
        if (persistentAnchors === undefined) {
            throw new Error("Persistent anchor enumeration is not supported in this environment/browser");
        }
        return persistentAnchors;
    }

    /**
     * Request a persistent handle for a tracked anchor
     * @param anchor The Babylon anchor to persist
     * @returns A promise that resolves with the persistent handle
     * @throws If requesting persistent handles is not supported by the native anchor
     */
    public async requestPersistentHandleAsync(anchor: IWebXRAnchor): Promise<string> {
        const requestPersistentHandle = anchor.xrAnchor.requestPersistentHandle;
        if (!requestPersistentHandle) {
            throw new Error("Requesting persistent anchor handles is not supported in this environment/browser");
        }
        const handle = await requestPersistentHandle.call(anchor.xrAnchor);
        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;

View on GitHub (pinned to 0592b347b8)

Solutions

Check typeof anchor.xrAnchor.requestPersistentHandle === 'function' before calling
Request anchor persistence features during session creation
Skip persistence (keep anchor for session lifetime only) when unsupported
Update device OS/browser to a version implementing persistent anchors

Example fix

// before
const handle = await anchorSystem.requestPersistentHandleAsync(anchor);
// after
if (typeof anchor.xrAnchor.requestPersistentHandle === 'function') {
  const handle = await anchorSystem.requestPersistentHandleAsync(anchor);
} else {
  console.warn('anchor persistence unsupported; skipping');
}

Defensive patterns

Strategy: type-guard

Validate before calling

const canPersist = typeof anchor.xrAnchor.requestPersistentHandle === 'function';

Type guard

function canRequestHandle(a: IWebXRAnchor): boolean {
  return typeof a.xrAnchor.requestPersistentHandle === 'function';
}

Try / catch

try {
  const handle = await anchorSystem.requestPersistentHandleAsync(anchor);
} catch {
  console.warn('anchor persistence unsupported; anchor kept for this session only');
}

Prevention

Check requestPersistentHandle existence before calling
Request persistence features at session creation
Store persistence availability per device and adapt UX
Skip persistence gracefully instead of failing the whole flow

When it happens

Trigger: Calling requestPersistentHandleAsync(anchor) where anchor.xrAnchor.requestPersistentHandle is undefined — runtime lacks persistent anchor support, or the anchor came from a session without persistence negotiated.

Common situations: Targeting devices that support transient anchors only, session created without the persistence feature, running on emulators or older WebXR implementations.

Related errors

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