{"record":{"id":"13fe57a8c8168c13","repo":"SixLabors/ImageSharp","slug":"the-image-is-not-a-valid-qoi-image","errorCode":null,"errorMessage":"The image is not a valid QOI image.","messagePattern":"The image is not a valid QOI image\\.","errorType":"exception","errorClass":"InvalidImageContentException","httpStatus":null,"severity":"error","filePath":"src/ImageSharp/Formats/Qoi/QoiDecoderCore.cs","lineNumber":132,"sourceCode":"\n        int channels = stream.ReadByte();\n        if (channels is -1 or (not 3 and not 4))\n        {\n            ThrowInvalidImageContentException();\n        }\n\n        int colorSpace = stream.ReadByte();\n        if (colorSpace is -1 or (not 0 and not 1))\n        {\n            ThrowInvalidImageContentException();\n        }\n\n        this.header = new QoiHeader(width, height, (QoiChannels)channels, (QoiColorSpace)colorSpace);\n    }\n\n    [DoesNotReturn]\n    private static void ThrowInvalidImageContentException()\n        => throw new InvalidImageContentException(\"The image is not a valid QOI image.\");\n\n    private void ProcessPixels<TPixel>(BufferedReadStream stream, Buffer2D<TPixel> pixels)\n        where TPixel : unmanaged, IPixel<TPixel>\n    {\n        using IMemoryOwner<Rgba32> previouslySeenPixelsBuffer = this.memoryAllocator.Allocate<Rgba32>(64, AllocationOptions.Clean);\n        Span<Rgba32> previouslySeenPixels = previouslySeenPixelsBuffer.GetSpan();\n        Rgba32 previousPixel = new(0, 0, 0, 255);\n\n        // We save the pixel to avoid losing the fully opaque black pixel\n        // See https://github.com/phoboslab/qoi/issues/258\n        int pixelArrayPosition = GetArrayPosition(previousPixel);\n        previouslySeenPixels[pixelArrayPosition] = previousPixel;\n        byte operationByte;\n        Rgba32 readPixel = default;\n        Span<byte> pixelBytes = MemoryMarshal.CreateSpan(ref Unsafe.As<Rgba32, byte>(ref readPixel), 4);\n        TPixel pixel = default;\n\n        for (int i = 0; i < this.header.Height; i++)","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/SixLabors/ImageSharp/blob/59ce6af6fc29027cda277ef62d4d1694a8acce91/src/ImageSharp/Formats/Qoi/QoiDecoderCore.cs#L114-L150","documentation":"QoiDecoderCore.ThrowInvalidImageContentException throws InvalidImageContentException with 'The image is not a valid QOI image.' as a shared guard for any structural mismatch found while parsing a QOI stream. It is called from ProcessHeader (bad magic marker, channels, or color-space bytes) and from ProcessPixels (unexpected end of stream / missing end marker), so any decode-stage QOI structural failure funnels here.","triggerScenarios":"Loading a file that starts with the wrong 4-byte magic ('qoif' expected); a channels byte that is not 3 or 4; pixel data that terminates before the 0x01 8-byte QOI end marker is found during ProcessPixels.","commonSituations":"Renaming a non-QOI file to .qoi; truncated uploads/failed downloads cutting off the end marker; encoders omitting the footer; probing unknown binaries with the QOI decoder.","solutions":["Confirm the file really is QOI: check the first four bytes are 'qoif' and the last 8 bytes are the end marker (0x01 followed by seven zero bytes).","Re-export the image with a spec-compliant QOI encoder; if truncated, re-transfer the file.","Let Image.Identify detect the real format first, then load with the matching decoder.","Catch InvalidImageContentException around the load and surface a 'not a valid QOI file' message."],"exampleFix":"// before\nusing var image = Image.Load(\"mystery.qoi\");\n// after\nif (!File.ReadAllBytes(\"mystery.qoi\").AsSpan(0, 4).SequenceEqual(\"qoif\"u8))\n{\n    throw new InvalidDataException(\"File lacks the QOI 'qoif' magic.\");\n}\nusing var image = Image.Load(\"mystery.qoi\");","handlingStrategy":"validation","validationCode":"// Verify QOI structural markers before decode.\nbyte[] all = File.ReadAllBytes(path);\nbool ok = all.Length >= 22\n    && all.AsSpan(0, 4).SequenceEqual(\"qoif\"u8)\n    && all[^8] == 0x01 && all[^7..].ToArray().All(b => b == 0);\nif (!ok) throw new InvalidDataException(\"File is not a structurally valid QOI image.\");","typeGuard":null,"tryCatchPattern":"try { using var img = Image.Load(path); }\ncatch (InvalidImageContentException) { HandleUnknownFormat(path); }","preventionTips":["Use Image.Identify to detect the true format instead of trusting extensions.","Check for the 'qoif' magic and footer marker on all ingested .qoi files.","Guard against truncated transfers with size/checksum validation.","For arbitrary uploads, probe format first, then dispatch to the right decoder."],"tags":["qoi","image-decoding","invalid-format","magic-bytes"],"backgroundTag":"schema-validation-failed","analyzedSha":"59ce6af6fc29027cda277ef62d4d1694a8acce91","analyzedAt":"2026-09-13T18:34:59.331Z","contentChangedAt":"2026-09-13T18:34:59.331Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}