Skip to main content

Troubleshooting

Use these guides to diagnose common Imgwire issues across uploads, transformations, custom domains, billing, account access, and production delivery.

Astronaut troubleshooting a broken rocket with the hatch open

Start with the symptom​

SymptomStart here
Upload creation fails or an image stays busyUploading Images
A transformed image looks wrongTransformations
A custom delivery hostname will not connectCustom Domains
Usage, payment, or plan access looks wrongBilling and Plans
You cannot sign in or access an EnvironmentAccount Access and Login
A live integration is failing in productionProduction Issues and System Status
You need help from ImgwireReport an Issue

Useful details to collect​

Before you change code, capture the exact failure. Good troubleshooting data usually includes:

  • The Imgwire Environment you are using.
  • The API endpoint or CDN URL that failed.
  • The HTTP status code and response body.
  • The image ID, if an image record was created.
  • Whether the request used a Client Key, Server Key, upload token, OAuth-linked MCP connection, or dashboard session.
  • File name, MIME type, file size, and pixel dimensions for upload issues.
  • Transformation parameters for delivery issues.
  • Browser Origin and Accept headers when debugging CORS or format=auto.

Common integration checks​

  • Server API Keys belong only in trusted backend, local, or CI environments.
  • Client Keys are publishable and are intended for frontend upload flows and image lookup.
  • Standard uploads are two-step: create the Imgwire image record, then upload bytes to the returned upload_url.
  • CDN delivery URLs are public delivery URLs, not private authorization.
  • Transformations affect delivered variants, not the original uploaded image.
  • Custom domains are Environment-scoped and must be connected before you replace default CDN URLs.

Need help?​

If a guide does not resolve the issue, see Report an Issue. You can contact Imgwire at support@imgwire.dev, or visit imgwire.dev/support to find the Discord server link and get help from moderators and other developers.

Last updated at: May 8, 2026