{"record":{"id":"890eb4443092dcef","repo":"pixijs/pixijs","slug":"invalid-magic-number-in-dds-header","errorCode":null,"errorMessage":"Invalid magic number in DDS header","messagePattern":"Invalid magic number in DDS header","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/compressed-textures/dds/parseDDS.ts","lineNumber":89,"sourceCode":"\n        levelBuffers.push(levelBuffer);\n\n        offset += byteLength;\n\n        mipWidth = Math.max(mipWidth >> 1, 1);\n        mipHeight = Math.max(mipHeight >> 1, 1);\n    }\n\n    return levelBuffers;\n}\n\nfunction parseDDSHeader(buffer: ArrayBuffer)\n{\n    const header = new Uint32Array(buffer, 0, DDS.HEADER_SIZE / Uint32Array.BYTES_PER_ELEMENT);\n\n    if (header[DDS.HEADER_FIELDS.MAGIC] !== DDS.MAGIC_VALUE)\n    {\n        throw new Error('Invalid magic number in DDS header');\n    }\n\n    // DDS header fields\n    const height = header[DDS.HEADER_FIELDS.HEIGHT];\n    const width = header[DDS.HEADER_FIELDS.WIDTH];\n    const mipmapCount = Math.max(1, header[DDS.HEADER_FIELDS.MIPMAP_COUNT]);\n    const flags = header[DDS.HEADER_FIELDS.PF_FLAGS];\n    const fourCC = header[DDS.HEADER_FIELDS.FOURCC];\n    const format = getTextureFormat(header, flags, fourCC, buffer);\n\n    const dataOffset = DDS.MAGIC_SIZE + DDS.HEADER_SIZE\n        + ((fourCC === DDS.D3DFMT.DX10) ? DDS.HEADER_DX10_SIZE : 0);\n\n    return {\n        format,\n        fourCC,\n        width,\n        height,","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/pixijs/pixijs/blob/4b141e3ced7255b39c2114b6bca03421a37b2363/src/compressed-textures/dds/parseDDS.ts#L71-L107","documentation":"Thrown by parseDDSHeader when the first 32-bit word of the file does not equal the DDS magic value ('DDS ' = 0x20534444). This is the canonical sanity check that the byte stream is actually a DDS file before trusting any header fields.","triggerScenarios":"Pointing the DDS loader at a non-DDS file (PNG/JSON/text/binary garbage), a truncated file (fewer than 4 bytes), a file that was decompressed/corrupted in transit, or a wrong byte order (endianness). Also a misrouted URL that returns HTML (e.g. a 200 SPA fallback) and is parsed as DDS.","commonSituations":"Asset name collision where a .dds URL actually returns an HTML 404 page (200 status), a build tool that mangles binary files, or downloading the file in text mode corrupting bytes.","solutions":["Verify the file starts with bytes 'DDS ' (0x44 0x44 0x53 0x20) using a hex viewer.","Confirm the URL returns the actual binary DDS (check Content-Type and that it is not an HTML fallback).","Re-export or re-download the DDS in binary mode without transformation.","Ensure no text-mode read or base64 double-encoding is applied to the file."],"exampleFix":"// before\nawait Assets.load('textures/floor.dds'); // actually returns HTML SPA fallback\n\n// after\n// fix server to return the real .dds binary (200, application/octet-stream)","handlingStrategy":"validation","validationCode":"// Verify the DDS magic before handing the buffer to the parser\nfunction isDdsMagic(buf: ArrayBuffer): boolean {\n  const v = new Uint32Array(buf, 0, 1)[0];\n  return v === 0x20534444; // 'DDS '\n}","typeGuard":"function isDdsBuffer(buf: ArrayBuffer): boolean {\n  if (buf.byteLength < 4) return false;\n  return new Uint32Array(buf, 0, 1)[0] === 0x20534444;\n}","tryCatchPattern":"try {\n  await Assets.load(url);\n} catch (err) {\n  if (String(err).includes('Invalid magic number in DDS header')) {\n    // wrong file or HTML fallback; verify URL and Content-Type\n  } else throw err;\n}","preventionTips":["Ensure .dds URLs return the binary file, not an HTML SPA fallback.","Download/serve binary assets without text-mode transformation.","Verify the file begins with the 'DDS ' magic bytes.","Use correct Content-Type (application/octet-stream) for .dds."],"tags":["compressed-textures","dds","parsing","validation","corruption"],"backgroundTag":null,"analyzedSha":"4b141e3ced7255b39c2114b6bca03421a37b2363","analyzedAt":"2026-08-12T17:27:29.507Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}