Installation and formats
Trace linking, ABI, dynamic-library, and unknown format failures. Installation and ABI · Missing codecs
Troubleshooting
Preserve the complete error, input characteristics, actual versions, and a minimal reproducer before choosing a path. Process RSS, a file extension, or one export parameter is not enough to identify the cause.
Diagnose by symptom
Section titled “Diagnose by symptom”Access order
Reproduce out of order read and separate sequential input, random operations, and materialisation. Access-order errors
Memory and concurrency
Observe ImageRef counts, the Go heap, libvips caches, and RSS separately, then check concurrent ownership. Suspected leaks · Concurrency crashes
Colour and animation
Diagnose ICC, CMYK, colour shifts, lost frames, page-height, and GIF encoder parameters. Colour shifts · Animation and multi-page
Build a minimal reproducer
Section titled “Build a minimal reproducer”Keep the smallest input that triggers the issue and the full call parameters, record the binding and libvips versions, then verify load, transform, and export separately. Treat a signal as stable only after repeated runs reproduce it.
Quick index
Section titled “Quick index”If you remember only an error or term, use the glossary, error, and resource index. If a version difference is likely, start with the version compatibility matrix.