#5010·libvips

Improve link from API calls to errors

Author: jcupittCreated Apr 23, 2026Updated Aug 25, 2026
Labelsenhancement

libvips API calls (eg. vips_image_new_from_file() or vips_add()) can fail and log error messages, but there is currently no reliable way to link an error message to a specific call.

Referring discussion: https://github.com/libvips/libvips/discussions/5009

Complications

  1. Errors can occur after the API call. For example _new_from_file() can fail when the first pixel is decoded, which may not happen until much later.
  2. Errors can occur before the API call. Results can come from the operation cache, and they might have errors from long before the API call that needs the result.
  3. Errors can be found in background workers, and they might be generating pixels for several top level functions.
  4. Errors in background threads can need to be passed to another thread for reporting.

Possible proposal?

  1. Have a parameter called context on VipsObject that holds an error buffer, and perhaps some other stuff.
  2. When an error occurs, log a message on the context of the nearest object (an operation, an image, a region, a source, etc.).
  3. Use vips_object_get_error(obj) to get an error message. This recursively walks the object and any associated objects (eg. down the image pipeline) and concatenates all the error buffers it finds.

(just a thought! maybe it wouldn't work)