Skip to main content

Troubleshooting Transformations

Use this guide when an Imgwire CDN URL does not render, a transformation is rejected, a resized image looks wrong, or format=auto returns a format you did not expect.

Check the URL shape first​

A standard Imgwire delivery URL uses this shape:

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?width=1200&format=auto&quality=auto

Preset suffixes go on the path before query parameters:

https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}@medium?format=auto&quality=auto

If you are using an SDK, prefer image.url(...), Imgwire React components, the CLI, or MCP URL generation over hand-building complex query strings.

Image does not load​

If the image returns a missing or failed response:

  • Confirm the organization_id, environment_id, and image_id are correct.
  • Retrieve the image record and confirm its status is READY.
  • Make sure you are using a CDN delivery URL, not the presigned upload URL.
  • If you are using a custom domain, test the default Imgwire CDN URL for the same image.
  • If the source format is not directly browser-friendly, request a browser-friendly format with format=auto.

CDN delivery URLs are public delivery URLs. They are not a private authorization layer.

Transformation parameter is rejected​

Most transformation issues come from an unsupported value, invalid range, or mismatched parameter name.

Use the individual transformation pages to check accepted values. Examples:

  • Format accepts auto, jpg, jpeg, png, webp, avif, gif, and tiff.
  • Quality accepts integers 1 through 100 or auto.
  • Width and Height accept 1 through 8192.
  • DPR accepts 0.01 through 8.
  • Resizing Type accepts cover, contain, fill, inside, and outside.

When in doubt, start with one transformation and add the rest incrementally:

?width=800
?width=800&format=auto
?width=800&format=auto&quality=auto

format=auto returns a different format than expected​

format=auto uses the request's Accept header. A browser, curl, image optimizer, crawler, or CDN debugging tool can each send different headers.

To debug negotiation, test with an explicit Accept header:

curl -I \
  -H "Accept: image/avif,image/webp,image/*,*/*" \
  "https://cdn.imgwire.dev/{organization_id}/{environment_id}/{image_id}?format=auto&quality=auto"

Use an explicit format when a downstream consumer requires one:

?format=jpeg&quality=85

Remember that format transformations affect the delivered variant, not the original uploaded image.

Crop or resize output looks wrong​

When an image needs to fit an exact box, use both dimensions and a resizing strategy:

?width=640&height=360&resizing_type=cover&format=auto&quality=auto

Common fixes:

  • Use cover when the image should fill the whole frame.
  • Use contain when the entire image must remain visible.
  • Avoid fill for photos unless distortion is acceptable.
  • Use crop=width:height:attention for smart crops when the important subject can move.
  • Use explicit gravity values such as north, southwest, or center when the composition is predictable.

See Crop, Gravity, and Resizing Type.

Image is larger than expected​

If a delivered image is too large:

  • Resize to the rendered slot with width and height.
  • Use format=auto&quality=auto for browser delivery.
  • Avoid sending a high-DPR image to every screen.
  • Use responsive srcset or <ResponsiveImage /> for fluid layouts.
  • Check whether you are viewing the original image URL without transformations.

Cache behavior is confusing​

Imgwire variants are cached by transformation intent. The same image with the same transformation should produce a reusable variant.

If you think the wrong variant is being served:

  • Compare the exact URL, including preset suffix and query parameters.
  • Check whether parameter aliases or different URL builders are producing separate URL shapes.
  • Use one canonical SDK-generated URL pattern for repeated UI slots.
  • If you uploaded a new source image, make sure the app is using the new image ID.

Last updated at: May 8, 2026