BabylonJS/Babylon.js · error · Error

Unable to deserialize TileCache.

Error message

Unable to deserialize TileCache.

What it means

BuildFromTileCacheData deserializes a tiled navmesh cache via Recast's importTileCache, which needs both the bytes and a TileCacheMeshProcess callback. It throws when the import returns no tileCache, meaning the WASM library could not parse the data as a tile cache — corrupt, truncated, or version-incompatible bytes.

Source

Thrown at packages/dev/addons/src/navigation/generator/generator.common.ts:39

    return {
        navMesh: result.navMesh,
        navMeshQuery: new recast.NavMeshQuery(result.navMesh),
        tileCache: undefined,
    };
}

/**
 * Builds a TileCache and NavMeshQuery from serialized data.
 * @param data The serialized TileCache data.
 * @param tileCacheMeshProcess Optional function to process the TileCache mesh.
 * @returns An object containing the TileCache, NavMesh, and NavMeshQuery.
 */
export function BuildFromTileCacheData(data: Uint8Array, tileCacheMeshProcess: TileCacheMeshProcess) {
    const recast = GetRecast();
    const result = recast.importTileCache(data, tileCacheMeshProcess);

    if (!result.tileCache) {
        throw new Error(`Unable to deserialize TileCache.`);
    }

    return {
        navMesh: result.navMesh,
        navMeshQuery: new recast.NavMeshQuery(result.navMesh),
        tileCache: result.tileCache,
    };
}

View on GitHub (pinned to 0592b347b8)

Solutions

1. Verify the serialized tile cache bytes (size, provenance) and that they were produced by `serialize` on the matching recast-navigation-js version.
2. Confirm you are calling the right builder — use BuildFromNavmeshData for monolithic navmeshes and this function only for tile-cache data.
3. Wrap in try/catch and regenerate the tile cache from geometry at load time as a fallback.

Example fix

// before
const nav = BuildFromTileCacheData(unknownBytes, meshProcess); // wrong data kind -> throws
// after
if (isTileCacheData(unknownBytes)) { // e.g. check magic header/size saved at export
  const nav = BuildFromTileCacheData(unknownBytes, meshProcess);
} else {
  const nav = BuildFromNavmeshData(unknownBytes);
}

const res = await fetch(tileCacheUrl);
if (!res.ok) throw new Error(`tilecache fetch failed: ${res.status}`);
const data = new Uint8Array(await res.arrayBuffer());
if (data.byteLength === 0) throw new Error("tilecache data empty");
const nav = BuildFromTileCacheData(data, tileCacheMeshProcess);

const isPlausibleTileCacheData = (d: Uint8Array): boolean => d.byteLength > 0;

try {
  nav = BuildFromTileCacheData(data, meshProcess);
} catch (e) {
  if (String(e).includes("Unable to deserialize TileCache")) {
    nav = rebuildTileCacheFromGeometry(meshProcess);
  } else throw e;
}

When it happens

Trigger: Calling BuildFromTileCacheData(data, tileCacheMeshProcess) with bytes that aren't a valid serialized tile cache (empty array, wrong asset, truncated download) or that were written by an incompatible Recast version/build.

Common situations: Loading tiled navmesh data saved by a different tool or library version; network transfer corruption; accidentally passing a monolithic navmesh dump (for BuildFromNavmeshData) instead of tile-cache data.

Related errors

• Unable to deserialize NavMesh.
• There is no TileCache generated.
• Recast is not initialized. Please call InitRecast first.
• At least one mesh is needed to create the nav mesh.
• Unable to get nav mesh. No vertices or indices.

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