siyuan-note/siyuan · error
ErrInvalid
ErrInvalid
Error message
heic: invalid file
What it means
ErrInvalid is the sentinel error of the h265heic isobmff parser, declared in kernel/heif/internal/h265heic/isobmff.go:28. It is returned when a byte stream is not a HEIF/HEIC container at all, or is so malformed that nothing can be decoded from it — box parsing exceeds the hard limits (65536 metadata boxes, 4096 top-level boxes) or the file structure is unreadable. It signals 'give up: no image data can be extracted from this input'.
Source
Thrown at kernel/heif/internal/h265heic/isobmff.go:28
maxContainerBytes = 32 << 20
maxMetadataBytes = 16 << 20
maxItems = 4096
maxProperties = 4096
maxItemExtents = 16384
maxItemReferences = 16384
maxItemProperties = 16384
maxItemDataBytes = 32 << 20
maxParameterSets = 64
maxParameterBytes = 1 << 20
maxNALUnits = 65536
maxNALBytes = 32 << 20
maxMetadataBoxes = 65536
maxTopLevelBoxes = 4096
)
// ErrInvalid is returned when a file is not a HEIF, or is malformed past the
// point where anything can be decoded from it.
var ErrInvalid = errors.New("heic: invalid file")
type reader struct {
b []byte
i int
err bool
}
func (r *reader) remaining() int {
if r.err {
return 0
}
return len(r.b) - r.i
}
func (r *reader) fail() {
r.err = true
r.i = len(r.b)View on GitHub (pinned to 8641553a1f)
Solutions
- Verify the file is a genuine HEIC container (bytes start with 'ftyp' box with heic/heix/mif1 brand) before parsing
- Re-download or re-export the image; a truncated file cannot be repaired by the parser
- Convert the image to HEIC with a known-good tool (e.g. libheif/ffmpeg) and retry
- Check file size — a 0-byte or few-byte file is guaranteed to fail
Example fix
// before
ret, err := h265heic.Parse(data)
// after
if len(data) < 12 || string(data[4:8]) != "ftyp" {
return fmt.Errorf("not a HEIC container")
}
ret, err := h265heic.Parse(data) Defensive patterns
Strategy: validation
Validate before calling
func looksLikeHEIC(b []byte) bool {
return len(b) >= 12 && string(b[4:8]) == "ftyp"
} Type guard
func isHEICBrand(b []byte) bool {
if len(b) < 12 || string(b[4:8]) != "ftyp" {
return false
}
brand := string(b[8:12])
return brand == "heic" || brand == "heix" || brand == "mif1" || brand == "hevc"
} Prevention
- Sniff the ftyp box and brand before parsing
- Check for minimum viable file size before parsing
- Re-download truncated files instead of retrying parses
- Quarantine files that fail parsing to avoid repeated failures
When it happens
Trigger: Parsing a file whose magic bytes are not a valid ISOBMFF/HEIF container; a truncated or corrupted .heic file; a file with more than 4096 top-level boxes or 65536 metadata boxes; feeding a JPEG/PNG or arbitrary bytes to the HEIC parser.
Common situations: Users paste an asset that was renamed to .heic but is actually another format; downloads truncated mid-transfer; fuzzed or intentionally malicious files; old phone exports with nonstandard box layouts.
Understand the failure class
Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.
Related errors
AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11).
Data as JSON: /api/errors/3fdaf207d0a992c2.
Report an issue: GitHub.