Troubleshooting

Optimization failed

If an image optimization fails, it does not count against your monthly quota. Common causes:

Image too small to compress further — if the image is already near or below the target file size, the app may not be able to reduce it further. Try lowering the target file size in Settings.
Unsupported format — the app processes JPEG, PNG, WebP, AVIF, and HEIC/HEIF. Other formats (GIF, SVG, BMP) are not supported for optimization.
Shopify processing delay — occasionally Shopify takes longer than expected to process an uploaded image. The app polls for confirmation, but if Shopify’s processing stalls, the optimization may time out. Try again after a few minutes.
Network interruption — if the connection between the app server and Shopify’s CDN drops during download or upload, the optimization will fail. Retry the image.

If you clicked Sync from Shopify but images aren’t appearing:

Wait a moment — the sync runs in the background. Large catalogs may take a minute to import.
Check the correct tab — product images and media images are on separate tabs. Make sure you’re looking at the right one.
Click Fetch Images — after syncing from the dashboard, go to the Images page and click Fetch Images on the tab you want to view.
Check product status — the sync imports images from active products only. Archived or draft products may not appear.

If the Rollback button is missing or grayed out:

Original expired — by default, originals are kept for 7 days. After expiry, rollback is no longer available. Check the image’s status — if it shows “Expired”, the original has been deleted. To prevent this, increase the rollback expiry in Settings or set it to 0 (forever).
Image was never optimized — rollback is only available for images that the app has optimized. Non-optimized images don’t have a stored original.

If the AI suggest button doesn’t produce results:

Plan check — AI alt text is only available on the Basic and Advanced plans. Free-plan users won’t see the AI suggest option.
Quota exhausted — check if you’ve used all your monthly AI suggestions (Basic: 200, Advanced: 500).
Provider configuration — the AI provider is configured server-side. If you see an error about API keys or providers, contact your store’s technical administrator to verify the AI provider configuration.

This means you’ve used all your monthly optimizations. Your options:

Wait for reset — your quota resets on your billing-cycle anniversary.
Upgrade your plan — upgrading gives you a higher quota immediately. Go to Plan in the sidebar.
Roll back and re-optimize later — rolling back images doesn’t count against your quota. You can roll back low-priority images and re-optimize them next month.

If optimized images appear lower quality than expected:

Increase initial quality — go to Settings and raise the initial quality percentage (try 85–90%).
Raise the target file size — increasing the target from 400 KB to 600–800 KB gives the compressor more room.
Reduce max iterations — fewer iterations mean less aggressive compression.
Roll back and adjust — roll back the affected images, change your settings, and re-optimize.

For stores with thousands of images, the initial sync can take a while:

Be patient — the sync fetches metadata from Shopify’s API in batches. Large catalogs (5,000+ images) may take a few minutes.
Don’t navigate away — stay on the dashboard while the sync completes. The page auto-refreshes when done.
Check your connection — a stable internet connection helps ensure the sync completes without interruption.

If the app fails to load inside Shopify admin:

Refresh the page — try a hard refresh (Ctrl/Cmd + Shift + R).
Clear browser cache — sometimes stale cached data can cause issues.
Check system status — verify that Shopify’s services are operational at status.shopify.com.
Reinstall the app — as a last resort, uninstall and reinstall. Note that this clears all optimization history and stored originals.

If your issue isn’t covered here, contact support at support@vibebun.com with: