Skip to content
VIPS HandbookVIPS Handbook

Unknown formats and missing codecs

Copy page

image: unknown format and xxxsave not found can both look like missing format support, but they come from different layers. The former means that the current detection path did not recognise the input; the latter means that the runtime libvips lacks the required load or save operation.

Symptoms

Section titled “Symptoms”
  • Loading or saving a specific format (JXL, BMP, and others) reports image: unknown format.
  • gifsave buffer not found or another save operation is missing.
  • Loading an animated WebP/AVIF reports unknown format even though the file opens elsewhere.
  • BMP is meant to go through libvips but falls back to Go’s standard-library decoder.

Identify the failing layer first

Section titled “Identify the failing layer first”

1. govips cannot recognise the input signature

Section titled “1. govips cannot recognise the input signature”

govips first recognises JPEG, PNG, GIF, TIFF, WebP, AVIF, HEIF, SVG, BMP, JPEG 2000, JPEG XL, PDF, and other types from their headers. DetermineImageType returns ImageTypeUnknown when the input is too short, truncated, mislabelled, or uses a sub-format that the current govips version does not recognise.

govips v2.19.0 already registers the Go GIF, JPEG, PNG, and WebP decoders inside the package. WebP comes from golang.org/x/image/webp, not image/webp. An application does not need to repeat these imports merely to use govips. A separate application path that calls image.Decode directly still needs to ensure that its required decoders are registered.

Read at least 12 bytes, call DetermineImageType, and then use IsTypeSupported to check the runtime support for the detected type. Do not infer the type only from the filename extension.

2. Runtime libvips lacks the loader or saver

Section titled “2. Runtime libvips lacks the loader or saver”

Errors such as gifsave_buffer not found or heifload not found mean that the runtime has no matching operation. libvips may be too old, or it may have been built without an optional dependency such as giflib, libheif, libjxl, or a PDF loader. The binding version alone cannot distinguish those cases.

Record the runtime with vips --version, then inspect registered operations with vips -l foreign or vips -l | grep -i <format>. Run the same check in the build and production images so a different runtime libvips cannot hide behind a successful compile stage.

3. Animated formats not recognised by the type detector

Section titled “3. Animated formats not recognised by the type detector”

Some govips releases did not recognise every animated AVIF/WebP signature. Test the file with the libvips CLI first, then reproduce with the locked govips version. A CLI success paired with a govips failure is stronger evidence of a binding-side detector defect.

Debug steps

Section titled “Debug steps”
  1. Confirm that the input is not empty, truncated, or merely carrying the wrong extension.
  2. Record the result of DetermineImageType.
  3. Call IsTypeSupported, then inspect the runtime loader or saver with vips -l.
  4. If the CLI loads the file but govips does not, record both versions and check for a fixed signature-detection defect.

Affected versions and scope

Section titled “Affected versions and scope”
  • This page was checked against govips v2.19.0 source. Earlier releases can have different built-in detection rules and decoder imports.
  • Format support depends on the runtime libvips build; it cannot be inferred from an extension or binding version alone.
  • Application code that calls Go’s image package directly remains responsible for its own decoder registration. That is separate from the registration already performed inside govips.

Sources

Section titled “Sources”