Troubleshooting Common Issues with AltTexty

We strive to make AltTexty as intuitive and reliable as possible. However, if you encounter an issue, this guide provides steps to diagnose and resolve common problems.

Remember, our Support Team is always here to help if you get stuck!

1. Alt Text Isn’t Generating Images (or Images are Skipped) #

This is one of the most common queries. Here’s a checklist:

Is Your AltTexty License Active?
- Check: Go to AltTexty -> Settings “License” tab. Ensure your license key is entered correctly and that there isn’t an error message indicating an inactive or invalid license.
- Action: If your license is inactive or invalid, please verify your subscription status on our website or contact support.
Do You Have Generation Credits?
- Check: Go to AltTexty -> Settings “Account” tab. Your account page should show your current credit balance.
- Action: If you’re out of credits, you may need to wait for your reset, topup or consider upgrading your plan.
Check “Allowed File Extensions”:
- Check: Go to AltTexty -> Settings -> Behavior -> Allowed File Extensions.
- Ensure the extensions of the images you’re trying to process (e.g., jpg, png, webp, svg) are listed here. If this field is blank, AltTexty will attempt to process all WordPress-recognized image types.
- Action: Add any missing extensions, separated by commas.
Review the AltTexty Log:
- Check: Go to AltTexty -> Log. This is your best friend for troubleshooting!
- Look for entries related to the specific image ID(s) or the time the generation was attempted.
- Common Log Messages:
  - Skipped: Alt text already exists...: This means the image had alt text, and your “Overwrite Existing Alt Text” setting (on the main Settings page or implicitly in Bulk Generate) prevented overwriting. This is expected behaviour based on settings.
  - API Error: ...: This indicates an issue communicating with the AI generation service. The message might provide more clues (e.g., authentication failure, rate limits, provided image is not valid, etc).
  - Could not determine image mime type or Invalid or missing Image URL: Problems fetching or identifying the image.
  - Skipped due to file extension...: The image’s file type isn’t in your “Allowed File Extensions.”
- Action: Address the specific error message. If it’s an API error, ensure your license is active and there are no widespread service issues. Contact support for this.
Global “Overwrite Existing Alt Text” Setting:
- Check: Go to AltTexty -> Settings -> Behaviour -> Overwrite Existing Alt Text.
- If this is set to “Never overwrite” or “Only if alt text is empty,” AltTexty will skip images that already have alt text when using single “Generate” buttons or “Auto-generate on Upload.”
- Action: Adjust this setting if you intend to overwrite existing alt text in those scenarios. (Note: The Bulk Generate page has its own overwrite logic when “Process all images” is selected).
SVG Specifics:
- If you’re trying to process SVGs, remember that AltTexty analyzes their code structure. Complex SVGs might not yield perfect results, or the AI might struggle to interpret them. The error “The AI could not process the SVG format directly…” indicates this.
- Ensure svg is in “Allowed File Extensions.”

2. Bulk Generation Seems Stuck, Very Slow, or Times Out #

Keep the Page Open: The Bulk Generate process (from AltTexty -> Bulk Generate) runs in your browser. You must keep that page open and active until it completes. Closing the tab or navigating away will stop the process.
Server Resources & Timeouts: Processing many images can be resource-intensive.
- Check Server Error Logs: Your web hosting provider can help you access PHP error logs or server logs, which might indicate timeouts or memory limit issues.
- Adjust Batch Settings: Go to AltTexty -> Settings -> Bulk Processing Performance.
  - Try decreasing the “Bulk Batch Size” (e.g., from 50 to 20 or 10). This processes fewer images per AJAX request.
Internet Connection: A spotty internet connection can interrupt the AJAX requests used by the bulk processor.
Plugin/Theme Conflicts: A JavaScript error from another plugin or your theme could interfere. Try basic conflict testing.
Browser Issues: Try a different web browser or clear your current browser’s cache and cookies.

3. Context Information (Title, SEO Keyphrases) Isn’t Appearing for My Images #

AltTexty can use the title or SEO keywords from the post an image is associated with to provide better context to the AI. If this isn’t working:

Check AltTexty Settings:
- Go to AltTexty -> Settings -> SEO & Post Context Integration.
- Ensure “Context Source” is set to “Use Parent Post Title” or “Use Parent Post SEO Keyphrases.”
- If using keyphrases, ensure “Select SEO Plugin” matches your active SEO plugin (e.g., Yoast, Rank Math).
- Check “Apply Context To” (Featured Images only / All attached images).
Verify SEO Plugin Data: Make sure the actual posts (that images are associated with) have titles and that you’ve entered focus keyphrases into your selected SEO plugin for those posts.
Image Association:
- AltTexty’s context system relies on an image being associated with a post. This association is stored in the “AltText Parent Post ID” meta field for the image.
- Initial Scan / Context Rescan: The “Initial Scan” (after plugin activation) and the manual “Context Rescan Tool” (from Settings) populate this based on the image’s WordPress post_parent (where it was uploaded or manually attached). Run the “Context Rescan Tool” if you’ve made changes to post titles, keywords, or image attachments.
- save_post Hook: When you save a post, AltTexty tries to update the context for its featured image and directly attached images. If “Sync Context for Embedded Images on Save” is enabled, a background task also processes images found within the content, potentially updating their WordPress post_parent and AltTexty context if they were unattached.
Check the AltTexty Log: Look for messages related to context syncing for the specific image or post IDs.

➡️ For a deep dive, see our KB article: How AltTexty Understands Image Context.

4. Specific Error Messages from the AltTexty Log #

“Invalid Image ID” / “Could not retrieve image URL”: The image AltTexty tried to process might have been deleted or is inaccessible.
“The AI could not process the SVG format directly…”: This is specific to SVGs. The AI couldn’t interpret the provided SVG code. See our SVG guide.
“API Request Failed: [Specific Error]”: Indicates a problem with the connection to the AI service or the service itself. The specific error might give more clues (e.g., “timeout,” “authentication failed,” “rate limit exceeded”).
“Generator Error: API handler is not available.”: A critical internal plugin error. Please contact support.

5. General WordPress Troubleshooting Steps #

If you suspect a conflict with another plugin or your theme:

Clear Caches: Clear all caching layers – your browser cache, any caching plugins (like WP Rocket, LiteSpeed Cache), and server-side caches (like Varnish, Memcached, Redis) if applicable.
Check Browser Console: Open your browser’s developer tools (usually by pressing F12) and look at the “Console” tab for any JavaScript errors when you’re using AltTexty pages.
Plugin Conflict Test (on a Staging Site if possible):
- Deactivate all other plugins except AltTexty.
- Test if the issue persists.
- If it’s resolved, reactivate your other plugins one by one, testing AltTexty after each, to find the conflicting plugin.
Theme Conflict Test (on a Staging Site):
- Temporarily switch to a default WordPress theme (like Twenty Twenty-Four or Twenty Twenty-Three).
- Test if the issue persists. If it’s resolved, your theme might be causing a conflict.

If you’ve gone through these steps and are still experiencing issues, please gather as much information as possible (screenshots, specific error messages from the AltTexty Log, steps to reproduce the problem) and contact our support team. We’re here to help you get AltTexty working smoothly!

What are your Feelings

Still stuck? How can we help?

Updated on 29/08/2025

Getting Started