{"record":{"id":"c059adc14c7868ff","repo":"BabylonJS/Babylon.js","slug":"unable-to-deserialize-navmesh","errorCode":null,"errorMessage":"Unable to deserialize NavMesh.","messagePattern":"Unable to deserialize NavMesh\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/dev/addons/src/navigation/generator/generator.common.ts","lineNumber":18,"sourceCode":"import { type TileCacheMeshProcess } from \"@recast-navigation/core\";\n\nimport { GetRecast } from \"../factory/common\";\n\n/**\n *  Builds a NavMesh and NavMeshQuery from serialized data.\n *  @param data The serialized NavMesh data.\n *  @returns An object containing the NavMesh and NavMeshQuery.\n *  @remarks This function deserializes the NavMesh data and creates a NavMeshQuery\n *  instance for querying the NavMesh.\n *  @throws Error if the NavMesh data is invalid or cannot be deserialized.\n */\nexport function BuildFromNavmeshData(data: Uint8Array) {\n    const recast = GetRecast();\n    const result = recast.importNavMesh(data);\n\n    if (!result.navMesh) {\n        throw new Error(`Unable to deserialize NavMesh.`);\n    }\n\n    return {\n        navMesh: result.navMesh,\n        navMeshQuery: new recast.NavMeshQuery(result.navMesh),\n        tileCache: undefined,\n    };\n}\n\n/**\n * Builds a TileCache and NavMeshQuery from serialized data.\n * @param data The serialized TileCache data.\n * @param tileCacheMeshProcess Optional function to process the TileCache mesh.\n * @returns An object containing the TileCache, NavMesh, and NavMeshQuery.\n */\nexport function BuildFromTileCacheData(data: Uint8Array, tileCacheMeshProcess: TileCacheMeshProcess) {\n    const recast = GetRecast();\n    const result = recast.importTileCache(data, tileCacheMeshProcess);","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/addons/src/navigation/generator/generator.common.ts#L1-L36","documentation":"BuildFromNavmeshData deserializes a previously saved navmesh by passing the raw bytes to Recast's importNavMesh. It throws when the import returns no navMesh object, meaning the WASM library could not parse the data — the bytes are corrupt, truncated, or were produced by an incompatible Recast version/build.","triggerScenarios":"Calling BuildFromNavmeshData(data) with a Uint8Array that is not a valid serialized navmesh: empty/garbage data, a file corrupted in transfer, or data serialized by a different recast-navigation-js version than the one initialized.","commonSituations":"Loading a saved .navmesh/.bin asset fetched over the network (404 HTML page or truncated download), version mismatch after upgrading the Recast WASM package, or passing tileCache data to the navmesh importer by mistake.","solutions":["Verify the data source: log/check `data.byteLength` and confirm the fetch returned the expected binary asset, not an error page.","Re-export/save the navmesh with the same recast-navigation-js version that is initialized at runtime.","Wrap the call in try/catch and fall back to rebuilding (generating) the navmesh from source geometry when deserialization fails."],"exampleFix":"// before\nconst data = new Uint8Array(await (await fetch(\"navmesh.bin\")).arrayBuffer());\nconst nav = BuildFromNavmeshData(data); // may throw on corrupt data\n// after\nconst res = await fetch(\"navmesh.bin\");\nif (!res.ok) throw new Error(\"navmesh download failed\");\nconst data = new Uint8Array(await res.arrayBuffer());\nconst nav = BuildFromNavmeshData(data); // only called with verified bytes","handlingStrategy":"validation","validationCode":"const res = await fetch(navmeshUrl);\nif (!res.ok) throw new Error(`navmesh fetch failed: ${res.status}`);\nconst buf = await res.arrayBuffer();\nif (buf.byteLength === 0) throw new Error(\"navmesh data empty\");\nconst nav = BuildFromNavmeshData(new Uint8Array(buf));","typeGuard":"const isPlausibleNavmeshData = (d: Uint8Array): boolean => d.byteLength > 0 && d.byteLength % 4 === 0;","tryCatchPattern":"try {\n  nav = BuildFromNavmeshData(data);\n} catch (e) {\n  if (String(e).includes(\"Unable to deserialize NavMesh\")) {\n    nav = generateNavmeshFromSceneGeometry(); // rebuild fallback\n  } else throw e;\n}","preventionTips":["Verify HTTP status and non-empty payload before deserializing.","Save a version tag alongside serialized navmesh data and check it on load.","Pin the recast-navigation-js version used for both serialize and import."],"tags":["navigation","recast","deserialization","corrupt-data","wasm"],"backgroundTag":"deserialization-failed","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}