Possible Image Stack errors

Troubleshooting overview

Normally, a successfully converted image is returned with code 200, the converted content in the body, and the following set of headers in the response:

• X-Img-Server
• headers from origin
• X-IMG-Saved-Bytes
• X-IMG-Origin-Download-Time
• X-IMG-Processing-Time
• "Content-Type":"{image/webp or image/avif}"
• Content-Length
• X-GCDN-Origin-Size

However, you may encounter problems when using Image Stack. For example, an image might be delivered to your web page in its original state without Image Stack processing, or an image may not be displayed on the page at all.

This article describes all possible errors that may occur when working with Image Stack, and explains how to fix them.

How to check an image’s details for troubleshooting

The developer tools allow you to check your processed image’s status code, response headers, and body outputs.

1. Go to the page where you used Image Stack and open the developer tools (Ctrl+Shift+I for Chrome)

2. Navigate to the Network section on the top side

3. In the page elements list on the left of the page, click the image you want to examine

4. Use the headers section to view information about the selected image

Below, you will find a list of errors. You can identify the error you faced by comparing the status code, response headers, and body outputs provided for each case.

Common errors that result in a broken image

Error	Details	Causes	Solutions
Incorrect image request method	Status: 405 Response Headers: X-GCDN-Img-Server Body: "error": "method not found"	The used request method is not GET	Use the GET request method
Incorrect format for conversion in headers or query	Status: 400 Response Headers: X-Img-Server Body: "error": "only webp format supported"	An unsupported format has been chosen for conversion	Set WebP as the format for conversion
Image Stack internal error	Status: 500 Response Headers: X-Img-Server Body: "error": "<err>"	Internal Image Stack error	Contact our technical support team at support@gcore.com
Origin timeout	Status: 504 Response Headers: X-Img-Server Body: "error": "request to origin timeout: <err>"	The origin did not respond	Fix the outages of your origin
Too many requests to the origin	Status: 504 Response Headers: X-Img-Server Body: "error": "too many requests"	Your origin is receiving too many requests	Reduce the number of requests to your origin; you can do so with our paid Origin shielding option

Common errors that deliver an image in its original state

Note: The request’s body will be proxied from your origin. The response headers will include X-Img-Server and headers from the origin. The status code of the response will be 200 OK.

Error	Details	Causes	Solutions
Unsupported content type from the origin for the converter	Response Header: "IMG-SKIP-REASON":"detected content type <content type> is not supported"	The image format is not supported	Change the image format to JPG or PNG
Quality difference skips for jpeg	Response Header: "IMG-SKIP-REASON":"{webp/avif} will be bigger, than origin: OriginQ: <origin quality>, DesiredQ: <desired jpeg quality>"	Compression occurred incorrectly; the quality of the processed image is greater than or equal to the original image	Ensure that the original image isn’t already optimized; possible ways to solve the problem are described in the official WebP guide
Invalid response code from the origin	Response Header: "IMG-SKIP-REASON":"not valid response code from the origin; response code — {response code from client’s origin}"	Your origin responded to the Image Stack with a non-200 response code, and Image Stack could not receive the image	Ensure your origin responds to the Image Stack with a 200 status code

Compression and Quality operation errors

Note: The request's body will be proxied from your origin. The response headers will include X-Img-Server and headers from the origin. The status code of the response will be 200 OK.

Error	Details	Causes	Solutions
Rate limit exceeded	Response Header: "IMG-SKIP-REASON":"compression: rate limit is exceeded"	The rate limit for conversions to WebP and AVIF formats has been exceeded	Wait for the limit to renew, or request a limit increase by contacting support@gcore.com
Bad quality parameter	Response Header: "IMG-SKIP-REASON":"compression: bad quality parameter"	The quality parameter is invalid; we can't convert the quality value to a number	Please ensure you set a value in the range 0–100; learn more in our quality guide
Unsupported format of the fmt value	Response Header: "IMG-SKIP-REASON":"compression: unsupported format of the fmt query parameter"	You were trying to convert an image into an unsupported format	Set WebP or AFIV as the fmt value according to the guide
The WebP or AVIF format is not supported by the user client	Response Header: "IMG-SKIP-REASON":"compression: webp/avif format is not supported by the client"	The WebP or AVIF format is not supported by the browser where the webpage is loaded	Choose a browser that supports the required format
The output image size is bigger or equal to the original image size	Response Header: "IMG-SKIP-REASON":"compression: output image size is bigger than/equal to the original image size"	The output image size is too big	Set the output image size to be smaller than the original image
Conversation to WebP or AVIF internal error	Response Header: "IMG-SKIP-REASON":"compression: {image/webp or image/avif} conversation internal error"	Internal conversion error	Contact our technical support team at support@gcore.com

Resize operation errors

Note: The request’s body will be proxied from your origin. The response headers will include X-Img-Server and headers from the origin. The status code of the response will be 200 OK.

Error	Details	Causes	Solutions
Bad “width” parameter	Response Header: "IMG-SKIP-REASON":"resizing: bad width parameter"	The width parameter is invalid. We cannot parse the value to a number	Please ensure you set a positive number; learn more in our resize guide
Bad “height” parameter	Response Header: "IMG-SKIP-REASON":"resizing: bad height parameter"	The height parameter is invalid. We can’t parse value to a number	Please ensure you set a positive number; learn more in our resize guide
The output image width or height parameter is larger than the original image size	Response Header: "IMG-SKIP-REASON":"resizing: destination image width or height parameter is more than the original image size"	You were attempting to convert the original image to a larger size	Convert the original image into a smaller size
Resizing internal error	Response Header: "IMG-SKIP-REASON":"resizing: internal error"	Internal Image Stack error	Contact our technical support team at support@gcore.com

Crop operation errors

Note: The request’s body will be proxied from your origin. The response headers will include X-Img-Server and headers from the origin. The status code of the response will be 200 OK.

Error	Details	Causes	Solutions
Bad “width-ratio” or “height-ratio” parameter	Response Header: "IMG-SKIP-REASON":"cropping: bad width-ratio or height-ratio parameter"	The count of ratio parameters is two or fewer	You must specify two values (numbers) with the “:” delimiter according to the guide
Bad “height ratio” parameter	Response Header: "IMG-SKIP-REASON":"cropping: bad height ratio parameter"	We can’t parse height value to an integer or value less than 0	Set the “height ratio” as a positive number according to the guide
Bad “width ratio” parameter	Response Header: "IMG-SKIP-REASON":"cropping: bad width ratio parameter"	We can’t parse width value to an integer or value less than 0	Set the “width ratio” as a positive number according to the guide
x or y parameter is not specified	Response Header: "IMG-SKIP-REASON":"cropping: x or y parameter is not specified"	The x or y parameters specifying the number of pixels to offset do not contain values	Specify the x and y values according to the guide
Bad x or/and y percentage parameter	Response Header: "IMG-SKIP-REASON":"cropping: bad x/y percentage parameter"	The x or y parameters cannot be parsed to an integer or have a value less than 0	Set the percentage between 0 and 100 [0, 100]
Bad x or y pixel parameter	Response Header: "IMG-SKIP-REASON":"cropping: bad x/y pixels parameter"	The x or y pixel parameters cannot be parsed to an integer or have a value less than 0	Set x or y as a positive number according to the guide
x and y pixels number parameter and percentage x and y parameter cannot be specified simultaneously	Response Header: "IMG-SKIP-REASON":"cropping: x/y pixel and percentage values cannot be specified simultaneously"	You have specified the x and y values twice: once by the number of pixels and once by the percentage x and y correlation	Choose only one method to specify the x and y values
Bad offset value for the x or y parameter	Response Header: "IMG-SKIP-REASON":"cropping: bad offset-x/y parameter"	The value of offset for x or y is empty	Specify x and y values for offset; it should be larger than 0
“width”, “height” and “width-ratio”:”height-ratio” values cannot be specified simultaneously	Response Header: "IMG-SKIP-REASON":"cropping: width={value},height={value} and width-ratio={value}:height-ratio={value} values cannot be specified simultaneously"	Pixels size parameters and aspect ratio are specified simultaneously	Choose only one method to specify the “width” and “height” or “width-ration” and “height-ratio”
x and y percentage parameter cannot be more than 100	Response Header: "IMG-SKIP-REASON":"cropping: x/y percentage parameter cannot be more than 100"	The x or y parameter is more than 100%	Set the x and y parameters between 0 and 100 [0, 100]
“offset x”, “offset-y” parameters cannot be more than 100	Response Header: "IMG-SKIP-REASON":"cropping: offset-x/y parameter cannot be more than 100"	The "offset-x“ or “offset-y” parameters are more than 100	Specify the “offest-x” and “offset-y” parameters as less than 100
Output “height” and “width” are bigger than the original image size	Response Header: "IMG-SKIP-REASON":"cropping: output height and width cannot be bigger than the original image size"	The “height” and “width” parameters are more than the width and height of the original image	Set the height and width parameters to be less than the original image
Output x or y pixel value is bigger than the original image value	Response Header: "IMG-SKIP-REASON":"cropping: output x/y pixel value cannot be more than the original image pixels"	The x or y pixel size of the output image is larger than the original image	Ensure the x and y pixel size of the output image is smaller than the original image
Output x or y percentage value cannot be more than the original image size	Response Header: "IMG-SKIP-REASON":"cropping: output x/y percentage value cannot be more than the original image size"	The correlation between the x and y percentage sizes of the output image is larger than the original image	Set the output image x and y percentage sizes to be less than the original image
Crop operation internal error	Response Header: "IMG-SKIP-REASON":"resizing: fit operation internal error"	The crop operation failed due to internal reasons	Contact our technical support team at support@gcore.com