{"record":{"id":"1e5d7539c4a37463","repo":"BabylonJS/Babylon.js","slug":"multi-file-loading-not-allowed-on-env-files","errorCode":null,"errorMessage":"Multi-file loading not allowed on env files.","messagePattern":"Multi-file loading not allowed on env files\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/core/src/Engines/Native/Extensions/nativeEngine.cubeTexture.pure.ts","lineNumber":102,"sourceCode":"                    imageData,\r\n                    false,\r\n                    texture._useSRGBBuffer,\r\n                    () => {\r\n                        texture.isReady = true;\r\n                        if (onLoad) {\r\n                            onLoad();\r\n                        }\r\n                    },\r\n                    () => {\r\n                        throw new Error(\"Could not load a native cube texture.\");\r\n                    }\r\n                );\r\n            };\r\n\r\n            if (buffer) {\r\n                onloaddata(buffer);\r\n            } else if (files && files.length === 6) {\r\n                throw new Error(`Multi-file loading not allowed on env files.`);\r\n            } else {\r\n                const onInternalError = (request?: IWebRequest, exception?: any) => {\r\n                    if (onError && request) {\r\n                        onError(request.status + \" \" + request.statusText, exception);\r\n                    }\r\n                };\r\n\r\n                this._loadFile(\r\n                    rootUrl,\r\n                    (data) => {\r\n                        onloaddata(new Uint8Array(data as ArrayBuffer, 0, (data as ArrayBuffer).byteLength));\r\n                    },\r\n                    undefined,\r\n                    undefined,\r\n                    true,\r\n                    onInternalError\r\n                );\r\n            }\r","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/core/src/Engines/Native/Extensions/nativeEngine.cubeTexture.pure.ts#L84-L120","documentation":"Environment (.env) cube textures are single-file formats containing all six faces plus specular data. The native cube texture loader therefore rejects a 6-element files array — multi-file (per-face) cube texture loading is only for non-env formats — and throws immediately.","triggerScenarios":"Calling NativeEngine's createCubeTexture/loadCubeTexture with both an env-style request and a files array of exactly 6 files (the multi-file per-face pattern used for plain cube faces), e.g. passing 6 face image files while the loader expects a single .env file or URL.","commonSituations":"Porting WebGL engine code that used 6 face files straight to Babylon Native with an env texture; configuring scene.environmentTexture with an array of six images instead of one .env; copy-paste from non-native cube texture examples that accept 6 files.","solutions":["Use a single .env file (export one from the Babylon.js sandbox / IBL baker) instead of six separate face files","If you only have six face images, pre-bake them into one .env or DDS cubemap file, then load that single file","If you truly need per-face loading, use the non-env cube texture API path (e.g. CubeTexture.CreateFromImages-style) rather than the env loader","Concatenate or convert face files at build time into a single container the native engine supports"],"exampleFix":"// before\nconst files = ['px.png','nx.png','py.png','ny.png','pz.png','nz.png'];\nnativeEngine.loadCubeTexture({ url: 'env', files }); // throws\n// after\nnativeEngine.loadCubeTexture({ url: 'assets/skybox.env' }); // single .env file","handlingStrategy":"validation","validationCode":"function assertNotMultiFileEnv(files?: string[] | null): void {\n  if (files && files.length === 6) {\n    throw new Error('env cube textures must be a single file; provide one .env instead of 6 face images');\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  const tex = nativeEngine.loadCubeTexture({ url, files });\n} catch (e) {\n  if (String(e.message).includes('Multi-file loading not allowed')) {\n    // convert face files to a single .env and retry\n  } else { throw e; }\n}","preventionTips":["Always ship IBL environment lighting as a single .env file","Bake six face images into one .env/DDS cubemap at build time","Audit ported WebGL code for 6-file cube patterns before moving to Babylon Native","Document the native engine's single-file env requirement in your asset pipeline"],"tags":["env-file","cube-texture","api-misuse","native-engine"],"backgroundTag":"multifile-cubemap-unsupported","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}