{"record":{"id":"78bf9b3b7d4ef07a","repo":"siyuan-note/siyuan","slug":"errunsupported","errorCode":"ErrUnsupported","errorMessage":"heic: unsupported image","messagePattern":"heic: unsupported image","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/heif/internal/h265heic/heic.go","lineNumber":44,"sourceCode":"[DecodeExif] reads the Exif item a file describes its image with, and\n[RawExif] and [RawXMP] return the payloads unparsed.\n*/\npackage heic\n\nimport (\n\t\"errors\"\n\t\"image\"\n\t\"io\"\n\t\"runtime\"\n\n\t\"github.com/gen2brain/h265/hevc\"\n)\n\n// ErrUnsupported is returned for a file this package cannot render but which\n// is otherwise well formed: an essential property it does not implement, or a\n// sample format it has no conversion for. A caller that has another decoder to\n// fall back on should test for this one rather than [ErrInvalid].\nvar ErrUnsupported = errors.New(\"heic: unsupported image\")\n\n// DefaultFrameSizeLimit 限制文件头能够请求分配的像素面积。\nconst DefaultFrameSizeLimit = 50_000_000\n\n// ColorInfo describes the color space an image was decoded from.\ntype ColorInfo struct {\n\tPrimaries uint16\n\tTransfer  uint16\n\tMatrix    uint16\n\tFullRange bool\n\t// ICCP is the embedded ICC profile, for files that carry one in place of\n\t// an nclx description. It aliases the input, so it is not a copy.\n\tICCP []byte\n}\n\n// Options controls decoding.\ntype Options struct {\n\t// AutoRotate applies the clap/irot/imir transforms, forcing NRGBA output","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/8641553a1f07374001902d3ce773285db1292b2d/kernel/heif/internal/h265heic/heic.go#L26-L62","documentation":"ErrUnsupported is the package's sentinel error (errors.Is-comparable) for files that are well-formed HEIF but use features this decoder does not implement — most notably grid images whose row*col tile count exceeds maxGridTiles, or whose item data layout exceeds the supported 12-byte structure. The doc comment explicitly tells callers with a fallback decoder to test for this error rather than ErrInvalid.","triggerScenarios":"decodeImage/decodeTiles/consumeDecodedBytes/parseGrid/gridOf on: (1) a grid-derived image with rows*cols > maxGridTiles (very large multi-tile photos), (2) grid item data with dataSize > 12 bytes (unsupported gridInfo layout), (3) sample formats or essential properties the decoder has no conversion for.","commonSituations":"ProRAW/ProMAX iPhone photos stored as large grid HEIFs with many tiles; images produced by newer camera firmware using grid extensions; HDR/auxiliary-layer images needing unimplemented conversions.","solutions":["Use errors.Is(err, h265heic.ErrUnsupported) to detect it and fall back to another decoder (system HEIF framework, ImageMagick, external converter)","Pre-convert oversized grid HEIFs to JPEG/PNG before importing","Check whether raising the decoder's limits (maxGridTiles/FrameSizeLimit options) accommodates your images","Verify the file opens in Preview/another viewer to confirm it is a capability gap, not corruption (corruption yields ErrInvalid instead)"],"exampleFix":"// before\nimg, err := h265heic.DecodeBytes(data, opts)\nif err != nil {\n\treturn nil, err\n}\n// after\nimg, err := h265heic.DecodeBytes(data, opts)\nif errors.Is(err, h265heic.ErrUnsupported) {\n\treturn fallbackDecode(data) // system decoder / external tool\n}\nif err != nil {\n\treturn nil, err\n}","handlingStrategy":"fallback","validationCode":"if errors.Is(err, h265heic.ErrUnsupported) {\n\tlog.Infof(\"HEIF uses unsupported features; using fallback decoder\")\n}\n// pre-check for very large grids when you control the pipeline:\n// reject images whose dimensions imply tile counts beyond maxGridTiles","typeGuard":null,"tryCatchPattern":"img, err := h265heic.DecodeBytes(data, opts)\nif errors.Is(err, h265heic.ErrUnsupported) {\n\treturn systemDecoder(data) // macOS/Windows HEIF codec, or external CLI\n}\nif err != nil {\n\treturn err // genuine corruption (ErrInvalid) or other failure\n}","preventionTips":["Always compare with errors.Is(err, h265heic.ErrUnsupported), never string matching","Build a fallback path (system codec or external converter) for unsupported features","Pre-convert large multi-tile HEIFs (ProRAW-class photos) at import","Distinguish ErrUnsupported (capability gap) from ErrInvalid (corrupt file) in telemetry"],"tags":["heif","unsupported-feature","grid-image","sentinel-error","fallback"],"backgroundTag":"unsupported-operation","analyzedSha":"8641553a1f07374001902d3ce773285db1292b2d","analyzedAt":"2026-09-11T16:08:28.414Z","contentChangedAt":"2026-09-11T16:08:28.414Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}