references/images/gotchas.md
Images Troubleshooting
First identify whether the failure involves hosted-image storage, remote URL transformations, or a Worker binding. Capture the failing operation, response status, relevant headers, and error message before changing options.
| Symptom or question | Documentation | |---------------------|---------------| | Resizing is absent, an origin request fails, or a transformation returns an error code | Troubleshooting | | Input size, dimensions, animation, or format compatibility | Limits and formats — choose the section for the affected interface | | Unexpected fit, quality, format, or crop behavior | Optimization features | | Binding input, output, or response handling fails | Binding methods | | Local behavior differs from production | Local binding development | | Private delivery fails or an image is unexpectedly public | Serve private images and variant public access | | Remote transformations appear stale | Caching and purging | | Worker transformations repeat unnecessarily | Binding caching guidance |
Do not apply one interface's limits, error codes, or caching rules to another. Reproduce with a representative image and verify the chosen fix using the project's existing checks. Retry only after identifying a transient failure; changing invalid inputs or access configuration requires a different fix. See API selection and configuration when the wrong interface or setup is responsible.