{"record":{"id":"cece4d52ec79b48c","repo":"BabylonJS/Babylon.js","slug":"restoring-persistent-anchors-is-not-supported-in-t","errorCode":null,"errorMessage":"Restoring persistent anchors is not supported in this environment/browser","messagePattern":"Restoring persistent anchors is not supported in this environment/browser","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/core/src/XR/features/WebXRAnchorSystem.pure.ts","lineNumber":337,"sourceCode":"        this._setPersistentHandle(anchor, handle);\r\n        return handle;\r\n    }\r\n\r\n    /**\r\n     * Restore a persistent anchor into the Babylon anchor lifecycle\r\n     * @param handle The persistent anchor handle to restore\r\n     * @returns A promise that resolves after the restored anchor is tracked by an XR frame\r\n     * @throws If restoring persistent anchors is not supported by the current session\r\n     */\r\n    public async restorePersistentAnchorAsync(handle: string): Promise<IWebXRAnchor> {\r\n        if (!this.attached) {\r\n            throw new Error(\"Restoring persistent anchors requires the anchor system to be attached\");\r\n        }\r\n\r\n        const session = this._xrSessionManager.session;\r\n        const restorePersistentAnchor = session?.restorePersistentAnchor;\r\n        if (!restorePersistentAnchor) {\r\n            throw new Error(\"Restoring persistent anchors is not supported in this environment/browser\");\r\n        }\r\n\r\n        const nativeAnchor = await restorePersistentAnchor.call(session, handle);\r\n        if (!this.attached || this._xrSessionManager.session !== session) {\r\n            nativeAnchor.delete();\r\n            throw new Error(\"Persistent anchor restoration was interrupted before tracking began\");\r\n        }\r\n        const existingAnchorIndex = this._findIndexInAnchorArray(nativeAnchor);\r\n        if (existingAnchorIndex !== -1) {\r\n            const existingAnchor = this._trackedAnchors[existingAnchorIndex];\r\n            existingAnchor.persistentHandle = handle;\r\n            return existingAnchor;\r\n        }\r\n\r\n        return await new Promise<IWebXRAnchor>((resolve, reject) => {\r\n            this._futureAnchors.push({\r\n                nativeAnchor,\r\n                resolved: false,\r","sourceCodeStart":319,"sourceCodeEnd":355,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/XR/features/WebXRAnchorSystem.pure.ts#L319-L355","documentation":"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.","triggerScenarios":"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.","commonSituations":"Runtimes implementing anchors transiently only, missing feature negotiation in requiredFeatures/optionalFeatures, older browser versions or emulators.","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"],"exampleFix":"// before\nconst anchor = await anchorSystem.restorePersistentAnchorAsync(handle);\n// after\nconst session = xrSessionManager.session;\nif (session && typeof session.restorePersistentAnchor === 'function') {\n  const anchor = await anchorSystem.restorePersistentAnchorAsync(handle);\n} else {\n  console.warn('persistent anchor restore unsupported');\n}","handlingStrategy":"type-guard","validationCode":"const session = xrSessionManager.session;\nconst restorable = !!session && typeof (session as any).restorePersistentAnchor === 'function';","typeGuard":"function supportsRestore(session: XRSession | undefined): session is XRSession & { restorePersistentAnchor(h: string): Promise<XRAnchor> } {\n  return !!session && 'restorePersistentAnchor' in session;\n}","tryCatchPattern":"try {\n  await anchorSystem.restorePersistentAnchorAsync(handle);\n} catch {\n  console.warn('restore unsupported here; dropping persistence for this handle');\n}","preventionTips":["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"],"tags":["webxr","anchors","persistence","feature-detection"],"backgroundTag":"missing-browser-api","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}