Troubleshoot image tools
Image tool problems fall into three groups: the tool is not available, an operation was rejected, or the output is unusable. Start by working out which.
The tool is not available
No entry under Media.
Check that the tool is enabled under Settings → POM AI → AI Tools, and that your user has the upload_files capability. All four image tools require it.
The screen loads but shows no images.
The media library search returned nothing. Clear the search field and page through instead — images with no title and no alt text are hard to find by search, which is exactly the set the metadata tool is for.
The operation was rejected
These messages appear before any work is done, and nothing is charged.
| Message | Cause | Fix |
|---|---|---|
| Please select at least one image | Nothing was ticked | Select an image |
| Please provide a description for your image | Empty prompt in the generator | Write a prompt |
| The prompt cannot exceed N characters | Over the limit | Shorten it; the counter shows the remaining allowance |
| You cannot select more than 48 images in a single operation | Metadata batch too large | Split the batch |
| You can select up to 3 reference images | Too many optional references | Remove one |
| Reference images must be 2 MB or smaller | Oversized reference | Use a smaller file |
| Only valid image attachments can be used as references | Not an image attachment | Choose a real image |
| The final prompt for image #N cannot exceed N characters | A per-image prompt pushed the combined prompt over | Shorten that image's additional prompt |
| WordPress media selector is not available on this screen | The media selector did not load | Reload the page |
Credit and license failures
| Symptom | Meaning |
|---|---|
| The credit notice says the balance could not be determined | No stored balance; check the License tab |
| An insufficient-credits message | The account balance or a domain limit was reached |
| Every operation fails immediately | Licensing, domain authorization or connectivity |
See Resolve an insufficient-credit error and Troubleshoot license and domain errors.
The operation started and failed
An error while calculating credits. The estimate request did not complete. Usually connectivity, a proxy stripping headers, or a security plugin blocking admin-ajax.php. Nothing was charged.
An error while generating. The service could not complete the work. Retry once; if it fails consistently for the same input and succeeds for others, the input is the problem — try a different source image or a simpler prompt.
Some images could not be processed. A batch completed with individual failures. The summary names them. The images that succeeded were charged; the failures were not. Re-run only the failures.
The run appears to hang. Image work takes time, and higher-quality profiles take longer. Watch the elapsed-seconds counter rather than resubmitting — a second submission is a second paid operation.
The output is unusable
Artefacts in the generated image. Regenerate with a more specific prompt, or a different style preset. See Write a useful image prompt.
The enhancement changed something it should not have. Say so explicitly in the prompt: name what must not change.
Poor background removal edges. Almost always the source. Higher resolution and better subject-background contrast make more difference than any setting. Consider a solid background colour instead of transparency. See Check a background removal.
Wrong metadata. The tool describes appearance without knowing context. Correct it by hand; see Write alternative text that helps.
The result is soft or low quality. Check the source resolution first, then compare a different model or a higher OpenAI quality for that single image.
After a replacing run
An image is missing on a page. The likely causes, in order: a hardcoded URL in a template or stylesheet, a cached page or CDN object, a reference stored in an unrecognised format, or a reference on a different site of a multisite network.
The original is gone and the result is bad. The original was force-deleted; there is no WordPress undo. Restore from backup. This is why Replace the original or create a new attachment recommends learning with new entries.
Persistent problems
If failures are consistent rather than occasional, check:
- outbound HTTPS from the server;
- PHP execution time and memory limits, which affect large uploads;
- the uploads directory is writable;
- any security plugin that filters
admin-ajax.phpor strips request headers; - whether the same operation succeeds on a different image.
Before contacting support
Collect the site URL, the POM AI version, the tool, the settings used — style, model, resolution, OpenAI quality, ratio, replace option — the number of images selected, the exact message copied not paraphrased, the time, and whether it reproduces.
Never send the license key. See Updates, support and safe maintenance.
Model or resolution errors
If a message asks you to select a supported model, resolution and quality, reload the tool and select those options again. The maximum width or height is 2560 pixels. Google 2K is unavailable at 9:16, 16:9 and 21:9; choose 1K for those ratios. For OpenAI, read the exact pixel dimensions and try a smaller resolution if the selected size is marked experimental.
If the selected model cannot complete a request, check the processing summary and credit history before trying again. Contact support if the same choice continues to fail, including the model, resolution and quality.