Image optimization (paid)
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
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.
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 |