Failure Diagnosis
Latest stable Based on Image release 0.3.0
Classify failures by boundary before changing image code.
Decode and format failures
Section titled “Decode and format failures”Confirm input bytes, content type, dimensions, and the selected backend. An extension is not proof of the encoded format. For SVG, TIFF, WebP, AVIF, and HEIC, verify that the required JVM or native codec is present. Reproduce with the smallest fixture and the exact release backend.
Native startup failures
Section titled “Native startup failures”UnsatisfiedLinkError or a missing-library message usually means libvips is absent or not visible to the process. Check package installation and dynamic-library search paths. Java 25 FFM also requires —enable-native-access=ALL-UNNAMED. Do not hide startup failure by silently switching backend unless fallback semantics are explicitly designed.
OCR failures
Section titled “OCR failures”“Error opening data file” points to missing traineddata or an incorrect data path. Verify tesseract —list-langs, requested language values, and process permissions. Distinguish empty recognized text from engine initialization failure.
Storage and route failures
Section titled “Storage and route failures”For local storage, check root path, traversal protection, directory permissions, and partial files. For S3 or CloudFront, check region, credentials, bucket/key policy, signing key, and clock. For Ktor, verify that JSON, error handling, authentication, and request limits are installed by the application.
Resource and shutdown failures
Section titled “Resource and shutdown failures”Growing native memory usually means a derived VipsImage was not closed or concurrency is unbounded. Failures after shutdown indicate runtime termination happened before workers drained.
Capture the failing input safely, backend, codec, dimensions, elapsed time, exception type, host package versions, and release commit. Avoid logging image contents or credentials.