{"record":{"id":"ad352f5c5f457ea7","repo":"SixLabors/ImageSharp","slug":"the-icon-directory-header-is-invalid","errorCode":null,"errorMessage":"The icon directory header is invalid.","messagePattern":"The icon directory header is invalid\\.","errorType":"exception","errorClass":"InvalidImageContentException","httpStatus":null,"severity":"error","filePath":"src/ImageSharp/Formats/Icon/IconDecoderCore.cs","lineNumber":298,"sourceCode":"        IconFrameCompression compression,\n        BmpBitsPerPixel bitsPerPixel,\n        ReadOnlyMemory<Color>? colorTable);\n\n    /// <summary>\n    /// Reads the icon directory entries needed by the configured frame limit.\n    /// </summary>\n    /// <param name=\"stream\">The source stream.</param>\n    [MemberNotNull(nameof(entries))]\n    private void ReadHeader(Stream stream)\n    {\n        Span<byte> buffer = this.buffer;\n\n        // ICONDIR\n        CheckEndOfStream(stream.Read(buffer[..IconDir.Size]), IconDir.Size);\n        this.fileHeader = IconDir.Parse(buffer);\n        if (this.fileHeader.Reserved != 0 || this.fileHeader.Type != this.iconFileType || this.fileHeader.Count == 0)\n        {\n            throw new InvalidImageContentException(\"The icon directory header is invalid.\");\n        }\n\n        // ICONDIRENTRY\n        int entryCount = (int)Math.Min(this.fileHeader.Count, this.Options.MaxFrames);\n        this.entries = new IconDirEntry[entryCount];\n        for (int i = 0; i < this.entries.Length; i++)\n        {\n            CheckEndOfStream(stream.Read(buffer[..IconDirEntry.Size]), IconDirEntry.Size);\n            this.entries[i] = IconDirEntry.Parse(buffer);\n        }\n    }\n\n    /// <summary>\n    /// Creates the decoder configured for an embedded PNG or headerless, double-height bitmap frame.\n    /// </summary>\n    /// <param name=\"isPng\">Whether the embedded frame has a PNG signature.</param>\n    /// <returns>The configured frame decoder.</returns>\n    private ImageDecoderCore GetDecoder(bool isPng)","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/SixLabors/ImageSharp/blob/59ce6af6fc29027cda277ef62d4d1694a8acce91/src/ImageSharp/Formats/Icon/IconDecoderCore.cs#L280-L316","documentation":"Thrown when the 6-byte ICONDIR header fails validation: the Reserved field is nonzero, the Type field does not match the expected icon type (1 = ICO, 2 = CUR), or the entry Count is zero. SixLabors.ImageSharp throws InvalidImageContentException because the file is not a valid icon resource.","triggerScenarios":"Calling Image.Load or Image.Identify on a file routed to the IconDecoder whose ICONDIR header has Reserved != 0, a Type other than 1/2 (or mismatched with the detected CUR/ICO type), or Count == 0; also on truncated headers that fail the preceding end-of-stream check indirectly.","commonSituations":"Files with a wrong extension that get detected as icon; hand-written or corrupted headers; empty .ico files with zero entries; CUR vs ICO type confusion.","solutions":["Confirm the file is a real ICO (starts with 00 00 01 00) or CUR (00 00 02 00) and has at least one directory entry","Re-export the icon from valid sources","Catch InvalidImageContentException and fall back or report the file as corrupt","Do not rename other image formats to .ico; let ImageSharp's format detection route them properly"],"exampleFix":"// before\nvar image = Image.Load(\"maybe.ico\");\n// after\nbyte[] head = File.ReadAllBytes(\"maybe.ico\")[..4];\nbool isIco = head[0] == 0 && head[1] == 0 && head[2] is 1 or 2 && head[3] == 0;\nif (!isIco) throw new InvalidOperationException(\"Not an ICO/CUR file\");\nvar image = Image.Load(\"maybe.ico\");","handlingStrategy":"validation","validationCode":"static bool IsValidIcoHeader(byte[] b) =>\n    b.Length >= 6 && b[0] == 0 && b[1] == 0 && b[2] == 1 && b[3] == 0 && (b[4] | (b[5] << 8)) > 0;\n// CUR uses b[2] == 2; ImageSharp picks the type from the detected format","typeGuard":"static bool IsInvalidImageContent(Exception ex) => ex is InvalidImageContentException;","tryCatchPattern":"try { var image = Image.Load(path); }\ncatch (InvalidImageContentException ex)\n{\n    // invalid icon directory header\n    throw new FormatException($\"{path} is not a valid ICO/CUR\", ex);\n}","preventionTips":["Do not rename PNG/other files to .ico","Validate the 6-byte ICONDIR (00 00 01 00 count ...) before loading","Generate icons with established tools"],"tags":["icon","ico","header-validation","invalid-image-content"],"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"}