Common Issues

Connection Errors

"Could not connect to API"

Cause: The WordPress plugin cannot reach the Flask API gateway.

Solutions:

• Verify the API URL in Settings → Picture Optimizer is correct (include /v1 suffix)
• Ensure your server allows outbound HTTPS requests on port 443
• Check if a firewall or security plugin is blocking external requests
• Test connectivity from your server: curl -I https://your-api-domain.com/image-forge-api/v1/credits/balance

"Invalid API key"

Cause: The API key is incorrect, expired, or deactivated.

Solutions:

• Re-copy the API key from your SerpTransformer dashboard
• Verify the key hasn't been deactivated in Settings → API Keys
• Generate a new key if the original is lost

Credit Issues

"Insufficient credits" Error

Cause: Your account doesn't have enough credits for the selected operation.

Solutions:

• Check your balance in the SaaS dashboard under Billing
• Reduce the number of images in your batch
• Switch to a cheaper pipeline mode (Analyze Only or Compress Only = 1 credit vs. Full = 2 credits)
• Purchase additional credits or upgrade your plan

Credits Deducted But Processing Failed

Credits are deducted at the start of each operation. If processing fails mid-batch:

• Individual image failures don't affect other images in the batch
• Contact support for credit refunds on failed operations

Bulk Processing Issues

414 Request-URI Too Large

Cause: When selecting a very large number of images (100+) via WordPress bulk actions, the browser may show a 414 Request-URI Too Large error. This happens because WordPress's default bulk action mechanism puts all selected media IDs into the URL as query parameters, which can exceed the server's URL length limit (typically 8KB).

Solution: This was fixed in plugin version 1.4.7. The plugin now intercepts the bulk action form submission with JavaScript, reads the selected IDs directly from the checkboxes, and opens the processing modal without a page redirect. No URL length limits apply.

If you're on an older version, update the plugin to v1.4.7+. As a workaround on older versions, process images in smaller batches (under 100 at a time).

Processing Issues

Images Stuck on "Uploading"

Cause: Large images or slow server connection.

Solutions:

• Check your server's upload_max_filesize and post_max_size PHP settings
• Increase PHP max_execution_time to at least 300 seconds
• Try processing fewer images at once

AI Analysis Returns Poor Results

Cause: The AI may struggle with abstract, text-heavy, or very small images.

Solutions:

• Use the Review step to edit AI-generated metadata before applying
• For text-heavy images (screenshots, infographics), manually write alt text
• Ensure images are at least 200x200 pixels for best AI performance

Export Produces Larger Files

Cause: Converting to a higher-quality format or using a high quality preset on already-compressed images.

Solutions:

• Use the Sample Preview to test settings before committing
• Try a lower quality preset (Medium or Low)
• Use WebP or AVIF for best compression ratios
• Keep the original format if the source is already well-optimized

URL & Replacement Issues

Broken Images After Processing

Cause: Some URL references weren't caught by the database search-and-replace.

Solutions:

• The .htaccess redirect should catch most missed references as a fallback
• Clear your browser cache and any page caching plugins
• Check if a CDN is serving cached versions of the old URL — purge the CDN cache
• Use the CDN integration hooks to automate cache purging

.htaccess Redirects Not Working

Cause: Server doesn't support .htaccess or mod_rewrite is disabled.

Solutions:

• Verify you're running Apache (not Nginx — .htaccess is Apache-only)
• Ensure mod_rewrite is enabled: a2enmod rewrite && systemctl restart apache2
• Check that AllowOverride All is set in your Apache config for the WordPress directory
• For Nginx, add equivalent rewrite rules manually in your server block

Revert Not Restoring URLs

Cause: The URL replacement map may be incomplete.

Solutions:

• Check that _image_forge_url_replacements post meta exists for the attachment
• Manually search your database for any remaining references to the processed filename
• Use a search-and-replace plugin (like Better Search Replace) for manual cleanup

Plugin Issues

Plugin Shows Wrong Version

Cause: Browser cache serving old JavaScript files.

Solutions:

• Hard refresh the page: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
• Clear browser cache
• The plugin uses version-based cache busting, so a hard refresh should load the latest JS

Modal Doesn't Open

Cause: JavaScript error or conflict with another plugin.

Solutions:

• Open browser developer tools (F12) and check the Console tab for errors
• Temporarily deactivate other plugins to identify conflicts
• Ensure jQuery is loaded (WordPress includes it by default)
• Verify the plugin files are complete — re-upload if necessary