Guide 1.16: Common Errors, Diagnostics and Support Requests
1. Introduction
SmartDescribe Pro helps WooCommerce store owners improve image alt text using AI. Like any WordPress plugin that interacts with external AI services, WooCommerce products, and other plugins, occasional errors may occur.
Most issues can be diagnosed by checking the plugin settings, confirming the AI provider configuration, reviewing the affected product, and testing the operation on a single item before attempting a bulk operation.
This guide explains how to identify common problems, perform basic troubleshooting, and prepare the information needed when contacting support.
Important: The exact error messages and available diagnostic options depend on the installed version of SmartDescribe Pro, the selected AI provider, and your WordPress environment.
2. Before You Begin Troubleshooting
Before changing settings or reinstalling the plugin, collect a few basic details.
Check the following:
- The installed SmartDescribe Pro version.
- Your WordPress version.
- Your WooCommerce version.
- Your PHP version.
- The AI provider you are using.
- Whether the issue affects one product or multiple products.
- Whether the issue started after a plugin, theme, WordPress, or PHP update.
- Whether the problem occurs during individual optimisation, bulk optimisation, or scheduled processing.
You can usually find your WordPress and server information under:
WordPress Dashboard → Tools → Site Health → Info
Your installed plugin version is generally shown under:
WordPress Dashboard → Plugins → Installed Plugins
Do not share your AI API key, WordPress password, hosting password, or other credentials when requesting support.
3. Problem: AI Optimisation Fails
Possible symptoms
- The optimisation does not complete.
- An error appears after starting the process.
- No new alt text is generated.
- The request appears to run but produces no result.
- Optimisation works for some products but fails for others.
Possible causes
- The AI provider API key is missing or incorrect.
- The selected AI model is unavailable to your account.
- The provider has temporarily limited requests.
- Your API account has insufficient credits or an inactive billing arrangement.
- The server cannot connect to the AI provider.
- The selected product does not contain a suitable image.
- A timeout or server-side error interrupts the request.
Recommended troubleshooting
- Open the SmartDescribe Pro settings.
- Confirm that the intended AI provider is selected.
- Check that the API key has been entered correctly.
- Confirm that the selected model is supported by your provider account.
- Check the provider’s dashboard for account, billing, usage, or service issues.
- Open a product that has a suitable image.
- Run optimisation on that single product.
- If the operation fails, record the exact error message.
If individual optimisation fails for every product, investigate the API configuration and server connection before attempting a large bulk operation.
If only one product fails, inspect that product’s image and product data before changing global settings.
4. Problem: API Key or Authentication Error
Possible symptoms
You may see an error indicating that the API key is invalid, authentication has failed, or the request is unauthorised.
Recommended troubleshooting
Step 1: Check the API key
Make sure the key belongs to the provider selected in SmartDescribe Pro.
For example, an OpenAI API key will not authenticate a request sent to Google Gemini.
Step 2: Check the key itself
Look for:
- Missing characters.
- Accidental spaces before or after the key.
- An incomplete copy-and-paste operation.
- A revoked, expired, or disabled key.
- Restrictions applied to the key or account.
Step 3: Check the provider account
Confirm that the account is active and has permission to use the requested model or service.
A paid ChatGPT subscription, for example, should not be assumed to include API usage credits. API access and billing are managed separately.
Step 4: Save the settings and test again
After correcting the configuration, save the settings and retry a single product.
Use the provider’s official dashboard to create or manage keys:
- Google Gemini: https://aistudio.google.com/apikey
- OpenAI: https://platform.openai.com/api-keys
- Anthropic: https://console.anthropic.com/settings/keys
Only use the provider relevant to your configuration.
Security reminder: Never include the complete API key in a support ticket, screenshot, public forum post, or diagnostic log.
5. Problem: The AI Model Is Unavailable
Possible symptoms
- The request returns a model-related error.
- The provider rejects the selected model.
- The model is no longer available.
- The account does not have access to the requested model.
Possible causes
- The model identifier is incorrect.
- The provider has changed its available models.
- The model is unavailable to your account or region.
- The provider has retired or restricted the model.
- The installed plugin version does not support the selected model.
Recommended troubleshooting
- Open the SmartDescribe Pro settings.
- Check the selected provider and model.
- Confirm the model is currently available through your provider account.
- Check the provider’s official documentation for model names and availability.
- If the plugin offers another supported model, select it and save your settings.
- Test the change on one product.
Do not assume that every model offered by an AI provider is supported by every version of SmartDescribe Pro.
If the model is valid but the request still fails, record the model name and the full error message, excluding any secret credentials.
6. Problem: API Rate Limit or Quota Exceeded
Possible symptoms
- Optimisation stops after several successful requests.
- Requests fail intermittently.
- The provider reports a rate limit or quota error.
- Bulk optimisation processes some products but not others.
Possible causes
AI providers may limit the number of requests made within a particular period. They may also impose usage quotas, account spending limits, or restrictions based on the selected model.
Recommended troubleshooting
- Check your AI provider’s usage dashboard.
- Determine whether the account has exceeded a quota or request limit.
- Allow any temporary rate limit to reset.
- Check whether the provider requires a billing or account change.
- If available, reduce the size of the next bulk operation.
- Retry a small group of products before restarting a larger job.
Avoid repeatedly clicking the optimisation button while a request is failing. This can generate additional requests without resolving the underlying issue.
If the provider is experiencing an outage or widespread service disruption, wait until the service is available again.
7. Problem: Bulk Optimisation Stops or Processes Only Some Products
SmartDescribe Pro’s bulk optimisation workflow has been tested for Lite and Pro. However, the size of a product catalogue and the limits of the hosting environment can affect how long a bulk operation takes.
Possible symptoms
- Only some selected products are processed.
- The progress indicator stops advancing.
- The operation appears to time out.
- Some products receive new alt text while others remain unchanged.
- The operation fails when processing a large selection.
Recommended troubleshooting
Step 1: Check the affected products
Identify which products were processed successfully and which remain unfinished.
Do not automatically assume that every product must be processed again.
Step 2: Test individual optimisation
Choose one of the products that failed and attempt to optimise it individually.
- If individual optimisation succeeds, the issue may relate to bulk processing, server limits, or request volume.
- If individual optimisation also fails, investigate the product, API configuration, or provider response.
Step 3: Reduce the workload
If the interface permits, process a smaller selection of products.
For example, instead of selecting hundreds of products at once, divide the catalogue into manageable groups.
Step 4: Check the hosting environment
Large operations may be affected by PHP execution limits, memory limits, network interruptions, or hosting restrictions.
Ask your hosting provider to check relevant server errors if the problem continues.
Step 5: Check for partial completion
Before restarting the operation, review the affected products to determine which alt text has already been updated.
Important: Do not assume that an interrupted bulk operation automatically resumes from the exact point where it stopped. Resumption behaviour depends on the installed version and the specific workflow.
8. Problem: Alt Text Is Not Changing
Possible symptoms
- Optimisation completes but the alt text appears unchanged.
- The generated text is identical to the existing text.
- The product still has an empty alt text field.
- The WordPress Media Library appears to show different text from the product page.
Recommended troubleshooting
Step 1: Confirm the correct image
Check which image is associated with the product and whether SmartDescribe Pro supports that image in your installed version.
Do not assume that optimising a product’s main image also updates every gallery image.
Step 2: Inspect the image’s alt text
Open the relevant image in the WordPress Media Library and inspect its alternative text field.
Where appropriate, also check the image through the product editing screen.
Step 3: Check the optimisation result
Confirm whether the operation generated new text or reported an error.
A completed request does not necessarily mean that the text changed. The existing alt text may already be suitable, or the generated result may be the same as the previous value.
Step 4: Check saving and permissions
Confirm that the user account has the necessary permissions and that WordPress can save the relevant changes.
Step 5: Check for conflicts
If the saved alt text is correct in WordPress but differs on the public website, investigate caching, image markup, theme behaviour, or other plugins.
Do not repeatedly run AI optimisation until you have identified whether the issue is generation, saving, or display.
9. Problem: Alt Text Appears Incorrect on the Public Website
Sometimes the WordPress image data is correct, but the public-facing page does not display the expected alternative text.
Possible causes include:
- Page or object caching.
- A theme or page builder generating different image markup.
- Another plugin modifying image output.
- The page displaying a different image from the one you edited.
- An image being loaded dynamically.
Recommended troubleshooting
- Open the affected product in WordPress.
- Check the relevant image’s saved alt text.
- Visit the public product page in a private or incognito browser window.
- Refresh the page and check whether the expected image is displayed.
- If necessary, clear the relevant WordPress, plugin, hosting, or CDN cache.
- Check the image markup to confirm which alt attribute is being output.
If the saved alt text is correct but the page output remains incorrect, investigate the theme and other image-related plugins before regenerating the text.
10. Problem: Scheduled Optimisation Does Not Run
If your installed version includes scheduled optimisation, an automation problem may prevent jobs from running at the expected time.
Possible causes
- The schedule has not been enabled or saved.
- The selected products or categories are not eligible for processing.
- WordPress scheduled tasks are delayed.
- The hosting environment restricts background processing.
- An AI provider request fails when the scheduled job runs.
- Another plugin or server configuration interferes with scheduled tasks.
Recommended troubleshooting
- Open the SmartDescribe Pro scheduling settings, if available.
- Confirm that scheduling is enabled.
- Review the selected products, categories, or other available scheduling options.
- Check whether the expected run time has passed.
- Test the same operation manually on one product.
- Review WordPress Site Health and relevant hosting logs.
- If the problem persists, ask your hosting provider to check scheduled-task execution.
WordPress scheduled tasks may depend on website traffic or the server’s cron configuration. A scheduled time should not automatically be treated as a guarantee that the operation will execute at that exact minute.
Do not enable additional cron jobs or change server configuration without understanding the implications for your website.
11. Problem: Plugin Settings Are Missing or Not Saving
Possible symptoms
- Settings appear to revert after saving.
- A provider or model selection is not retained.
- A settings page does not load correctly.
- The SmartDescribe Pro menu or page is missing.
Recommended troubleshooting
- Confirm that SmartDescribe Pro is active.
- Check that you are logged in with an account that has the required permissions.
- Refresh the dashboard and reopen the settings page.
- Save one setting at a time, where practical.
- Check for a WordPress error notice.
- Temporarily test whether a browser extension or cached page is affecting the interface.
- Review WordPress and server logs if the problem continues.
If the menu is missing, check whether the plugin is active and whether the current account has the necessary capabilities.
Do not delete plugin settings or reinstall the plugin as the first troubleshooting step. Those actions may be unnecessary and could complicate diagnosis.
12. Problem: A Conflict With Another Plugin or Theme
WordPress stores frequently use multiple plugins that affect products, images, SEO, caching, security, and administration.
Occasionally, two components may interfere with one another.
Possible signs
- The issue started after installing or updating another plugin.
- The WordPress dashboard displays an error.
- Product editing stops working.
- An optimisation button does not respond.
- Alt text appears correctly in the Media Library but not on the public page.
Recommended troubleshooting
Step 1: Record recent changes
Identify any plugin, theme, WordPress, WooCommerce, or PHP updates that occurred before the problem began.
Step 2: Check error messages
Look for relevant errors in WordPress Site Health and the hosting error logs.
Step 3: Test carefully
If a conflict is suspected, use a staging site where possible.
On the staging site, test with a default theme and a minimal set of plugins, then reintroduce components methodically.
Step 4: Identify the conflicting component
If the problem disappears when a particular component is disabled and returns when it is re-enabled, that is useful evidence of a possible conflict.
Caution: Do not deactivate security, payment, or other critical plugins on a live store without a safe testing plan. A staging environment is preferable.
13. Problem: WordPress Displays a Critical Error
If the WordPress dashboard or website displays a critical error after a plugin update or configuration change, prioritise restoring website access.
Immediate steps
- Record the error message and the action that triggered it.
- Check whether WordPress sent an administrator recovery email.
- If you cannot access the dashboard, use your hosting provider’s supported recovery method.
- Check the PHP error log for the relevant error and file.
- If the problem followed a recent update, follow your normal backup and recovery procedure.
Do not repeatedly activate and deactivate plugins without identifying the cause.
If you are not comfortable working with WordPress files or server logs, contact your hosting provider or WordPress developer.
A critical error may originate from SmartDescribe Pro, another plugin, the active theme, or the hosting environment. The timing of the error is useful evidence, but does not by itself prove which component caused it.
14. Checking WordPress and Server Logs
Logs can help distinguish an AI provider error from a WordPress, PHP, or hosting problem.
WordPress Site Health
Open:
WordPress Dashboard → Tools → Site Health
Review the available status and information sections for relevant warnings.
Hosting error logs
Your hosting control panel may provide PHP or server error logs.
Look for entries that match the time of the failed operation.
Useful information may include:
- The timestamp of the error.
- The affected PHP file.
- The error type and message.
- Whether the request timed out.
- Whether the error refers to memory, permissions, or a network request.
WordPress debug logging
If more detailed logging is required, a developer may enable WordPress debugging in a controlled manner.
Debugging should be configured carefully, especially on a live website. Avoid displaying PHP errors publicly.
If logging is enabled, protect the resulting log file because it may contain sensitive technical information.
Do not enable public error display simply to collect diagnostic details.
15. Preparing a Useful Support Request
A clear support request makes it easier to identify the cause of a problem.
Before contacting Cazgrae support, collect the following information.
Essential details
- Plugin: SmartDescribe Pro.
- Installed plugin version: The version displayed in WordPress.
- WordPress version: Your installed WordPress release.
- WooCommerce version: Your installed WooCommerce release, if applicable.
- PHP version: The version reported by your hosting environment.
- AI provider: The provider selected in the plugin.
- AI model: The selected model, if applicable.
- Problem type: Individual optimisation, bulk optimisation, scheduling, settings, or display.
- Error message: The complete error text, with sensitive details removed.
- Reproduction steps: The steps that consistently trigger the problem.
- Scope: Whether the issue affects one product, a group of products, or the whole website.
- Recent changes: Any relevant updates or configuration changes.
- Troubleshooting already attempted: The steps you have completed and their results.
Example support request
Use the following template to organise the information before sending your request.
Subject: SmartDescribe Pro — [Brief description of the problem]
Plugin version:
[Enter installed version]
WordPress version:
[Enter version]
WooCommerce version:
[Enter version, if applicable]
PHP version:
[Enter version]
AI provider and model:
[Enter provider and model, if applicable]
What I expected to happen:
[Describe the expected result.]
What actually happened:
[Describe the result or error.]
Steps to reproduce the problem:
- [First step]
- [Second step]
- [Third step]
Exact error message:
[Paste the error message, after removing sensitive information.]
Scope of the problem:
[One product, multiple products, bulk optimisation, or the entire website.]
Troubleshooting completed:
[List the tests you have performed and their results.]
Recent changes:
[Record relevant updates or configuration changes.]
This format provides a useful starting point for investigating the issue without unnecessary back-and-forth.
16. Screenshots and Diagnostic Information
Screenshots can help explain a problem that is difficult to describe in writing.
Useful screenshots may include:
- The SmartDescribe Pro settings page, with API keys hidden.
- The optimisation screen showing the affected product.
- The error message displayed by WordPress.
- The product image’s alt text field.
- The bulk optimisation screen showing the incomplete operation.
- The relevant WordPress or hosting error message.
Before sharing screenshots, remove or obscure:
- API keys and access tokens.
- Passwords and authentication details.
- Customer names, email addresses, and order information.
- Private website URLs or other information you do not want to disclose.
- Any other confidential information visible on the screen.
Do not send a full database export or complete server log unless support specifically requests it through an appropriate secure channel.
17. What Not to Do During Troubleshooting
To avoid creating additional problems, follow these precautions.
Do not repeatedly retry a failing operation.
Repeated requests can consume API quota and make diagnosis more difficult.
Do not immediately reinstall the plugin.
Reinstallation may not address an API, server, or compatibility problem.
Do not delete existing alt text to force regeneration.
Existing text may already be useful and should be preserved unless you have a clear reason to change it.
Do not make several changes at once.
Change one relevant setting at a time and test the result.
Do not run a large bulk operation while diagnosing an individual failure.
Start with a single product and expand only after confirming that the basic workflow works.
Do not expose debug information publicly.
Error messages and logs may reveal file paths, server details, or other sensitive information.
Do not edit plugin source files as a first response.
Direct code changes can introduce new errors and may be overwritten by future updates.
Do not assume the AI provider is responsible for every failure.
The issue may be in WordPress, WooCommerce, the hosting environment, another plugin, or the image data itself.
18. Quick Troubleshooting Reference
| Problem | First check | Recommended next step |
|---|---|---|
| AI optimisation fails | API key and provider settings | Test one product and record the error |
| Authentication error | API key validity and account access | Correct the key and retry |
| Model unavailable | Selected model and provider access | Choose a supported model |
| Rate limit or quota error | Provider usage and billing | Wait, resolve quota limits, or reduce request volume |
| Bulk process stops | Products completed and remaining | Test a failed product individually |
| Alt text does not change | Correct image and saved alt text | Check generation, saving, and display separately |
| Public page shows different text | WordPress image data and page output | Check caching, theme output, and image selection |
| Scheduled operation does not run | Scheduling settings and server tasks | Test manually and investigate scheduled-task execution |
| Settings do not save | Plugin status and account permissions | Check error messages and logs |
| Dashboard menu is missing | Plugin activation and user capabilities | Confirm activation and permissions |
| Critical WordPress error | PHP error log and recent changes | Restore access safely and investigate the underlying error |
| Problem follows another plugin update | Recent changes | Reproduce the issue on a staging site |
19. Recommended Troubleshooting Sequence
When a problem occurs, use this order of operations:
- Record the error. Capture the exact message and the action that caused it.
- Check the configuration. Confirm the provider, model, and relevant plugin settings.
- Test one product. Avoid large operations until the basic workflow succeeds.
- Inspect the image data. Check the image and its saved alt text.
- Check the provider. Review account access, usage, quotas, and service status.
- Check WordPress and hosting. Investigate relevant warnings, PHP errors, and timeouts.
- Consider conflicts. Review recent updates and test on staging where possible.
- Prepare a support request. Supply the version details, reproduction steps, and relevant error message.
This process helps narrow down the source of the problem before more disruptive changes are made.
20. Frequently Asked Questions
Should I reinstall SmartDescribe Pro whenever an error occurs?
No. First identify whether the issue relates to configuration, the AI provider, product data, WordPress, or the hosting environment. Reinstallation is not a universal fix.
Why does individual optimisation work while bulk optimisation fails?
Bulk operations place greater demands on request handling and may be affected by hosting limits, provider quotas, or the size of the selected workload. Test smaller groups and investigate any relevant server errors.
Why does the AI provider report an error when my API key is correct?
A valid key does not guarantee that the selected model is available or that the account has sufficient quota, billing access, or permission to make the request.
Can I send my API key to support?
No. Never send the complete API key. Provide the provider name, selected model, and error message with sensitive details removed.
Should I optimise all products again after an interrupted bulk operation?
Not automatically. First identify which products were completed and which remain unfinished. Retry only where needed.
What if I cannot access WordPress after an update?
Check the recovery email and hosting error logs, then follow your host’s recovery procedure. Contact your hosting provider or developer if you cannot safely restore access.
What if I cannot reproduce the error?
Record when it occurred, what you were doing, and any available error information. Intermittent errors can still be investigated using timestamps and logs.
Will every error be recorded inside SmartDescribe Pro?
Not necessarily. The diagnostic information available depends on the installed version and the type of failure. Some errors may appear only in WordPress or hosting logs, or in the AI provider’s dashboard.
21. Final Recommendations
The most effective way to troubleshoot SmartDescribe Pro is to isolate the problem before making changes.
Start with the plugin settings, test a single product, inspect the saved alt text, and check the AI provider’s response. If the issue continues, investigate the WordPress and hosting environment before attempting a reinstall or making code changes.
When contacting support, provide the installed plugin version, the exact error message, the steps required to reproduce the problem, and the troubleshooting you have already completed. Never include passwords, API keys, or unnecessary customer information.
SmartDescribe Pro troubleshooting principle: identify the failure, isolate its cause, test one change at a time, and protect your existing product data throughout the process.