{"record":{"id":"730f52efb846bcf0","repo":"stride3d/stride","slug":"unexpected-cubemap-expecting-all-faces-from-dds-header","errorCode":null,"errorMessage":"Unexpected CubeMap, expecting all faces from DDS Header","messagePattern":"Unexpected CubeMap, expecting all faces from DDS Header","errorType":"validation","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Foundation/Graphics/DDSHelper.cs","lineNumber":401,"sourceCode":"            }\n            else\n            {\n                description.ArraySize = 1;\n\n                if ((header.Flags & DDS.HeaderFlags.Volume) != 0)\n                {\n                    description.Width = header.Width;\n                    description.Height = header.Height;\n                    description.Depth = header.Depth;\n                    description.Dimension = TextureDimension.Texture3D;\n                }\n                else\n                {\n                    if ((header.CubemapFlags & DDS.CubemapFlags.CubeMap) != 0)\n                    {\n                        // We require all six faces to be defined\n                        if ((header.CubemapFlags & DDS.CubemapFlags.AllFaces) != DDS.CubemapFlags.AllFaces)\n                            throw new InvalidOperationException(\"Unexpected CubeMap, expecting all faces from DDS Header\");\n\n                        description.ArraySize = 6;\n                        description.Dimension = TextureDimension.TextureCube;\n                    }\n                    else\n                    {\n                        description.Dimension = TextureDimension.Texture2D;\n                    }\n\n                    description.Width = header.Width;\n                    description.Height = header.Height;\n                    description.Depth = 1;\n                    // Note there's no way for a legacy Direct3D 9 DDS to express a '1D' texture\n                }\n\n                description.Format = GetDXGIFormat(ref header.PixelFormat, flags, out convFlags);\n\n                if (description.Format == PixelFormat.None)","sourceCodeStart":383,"sourceCodeEnd":419,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Foundation/Graphics/DDSHelper.cs#L383-L419","documentation":"Thrown by DecodeDDSHeader when a DDS file declares the CubeMap flag in its dwCubemap field but does not set all six per-face bits (AllFaces). The library requires all six cube faces to be present in the file and refuses to load a partial cube map rather than producing an incomplete texture.","triggerScenarios":"Loading a .dds whose header sets DDCAPS2_CUBEMAP but omits one or more of DDCAPS2_CUBEMAP_POSITIVEX/NEGATIVEX/POSITIVEY/NEGATIVEY/POSITIVEZ/NEGATIVEZ flags, via any DDS decode entry point.","commonSituations":"DDS cube maps written by custom/buggy exporters that set the cubemap flag but forget the face flags; manually patched DDS headers; cube maps truncated during asset transfer.","solutions":["Re-export the cube map so all six face flags are set in dwCubemap2 (0xFC00 | 0x200).","Patch the DDS header cubemap face flags if the face data is known to be present (all 6 face-flag bits + the CubeMap bit).","If only a 2D texture was intended, remove the CubeMap flag from the header so the file decodes as Texture2D.","Wrap the load in a try-catch and treat the asset as invalid, prompting re-import."],"exampleFix":"// before\nvar tex = Texture.Load(ddsStream);\n\n// after\ntry { var tex = Texture.Load(ddsStream); }\ncatch (InvalidOperationException e) when (e.Message.Contains(\"expecting all faces\"))\n{\n    log.Error(\"DDS cubemap is missing face flags; re-export with all 6 faces\");\n}","handlingStrategy":"validation","validationCode":"// dwCubemap is at offset 28 of the DDS header (32 with magic)\nuint cubemap = BitConverter.ToUInt32(ddsBytes, 4 + 28);\nbool isCube = (cubemap & 0x200) != 0;\nbool allFaces = (cubemap & 0xFC00) == 0xFC00;\nif (isCube && !allFaces)\n    throw new InvalidDataException(\"DDS cubemap missing one or more face flags\");","typeGuard":null,"tryCatchPattern":"try { texture = DdsLoader.Load(stream); }\ncatch (InvalidOperationException e) when (e.Message.Contains(\"expecting all faces\"))\n{\n    texture = placeholderCubemap; // re-import asset\n}","preventionTips":["Verify cube maps set all six face flags in the exporter","Round-trip test exported DDS files through the loader","Reject partial cube maps at asset import"],"tags":["dds","cubemap","invalid-data"],"backgroundTag":"invalid-config-value","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}