SmartDescribe Pro Technical FAQs for Developers and Advanced Users | WooCommerce Plugins & Enhancements

Guide 1.17: Technical FAQs for Developers and Advanced Users

1. Introduction

SmartDescribe Pro is designed to help WooCommerce store owners improve product image alt text using AI. While routine optimisation is straightforward, developers and technically experienced administrators may occasionally need to investigate API errors, compatibility issues, server limitations, or unexpected changes to image metadata.

This guide addresses common technical questions and provides a structured approach to investigating more complex problems.

It is intended for:

WordPress developers.
WooCommerce store administrators.
Website maintenance providers.
Hosting support teams.
Advanced SmartDescribe Pro users.

Important: The exact implementation, available diagnostic features, database storage, hooks, and background-processing behaviour depend on the installed SmartDescribe Pro version. Do not assume that an undocumented function, database key, or developer hook exists without checking the actual plugin files.

2. Understanding the Optimisation Process

AI-assisted alt text optimisation generally involves several stages.

Product selection: The user selects an individual product or a group of products.
Image identification: The plugin identifies an eligible image associated with the selected product.
Configuration: The plugin obtains the configured AI provider, model, and applicable optimisation settings.
AI request: The plugin sends the necessary request to the configured provider.
Response processing: The plugin receives and interprets the generated text.
Validation: The result may be checked against applicable settings or constraints.
Saving: The resulting alt text is saved to the appropriate WordPress image data.
Display: WordPress, WooCommerce, the theme, and other components determine how the image and its alt attribute appear on the public website.

The exact sequence and available validation steps depend on the installed implementation.

Understanding these stages helps narrow down the source of a failure.

For example:

If the request is rejected, investigate the provider configuration and response.
If text is generated but not saved, investigate WordPress permissions and saving logic.
If the saved text is correct but the website displays something different, investigate image selection, caching, and front-end markup.

Diagnostic principle: Identify the stage where the process fails before changing unrelated settings.

3. Which WordPress and WooCommerce Versions Are Supported?

Compatibility depends on the requirements declared by the installed plugin release and the WordPress environment.

Before installing or updating SmartDescribe Pro, check:

The WordPress version.
The WooCommerce version.
The PHP version.
The plugin’s declared minimum requirements.
Any release notes describing compatibility changes.
Whether the environment meets the requirements of the selected AI provider’s integration.

Do not assume that a plugin works with every WordPress, WooCommerce, or PHP release simply because it activates successfully.

Recommended compatibility test

On a staging website:

Record the existing software versions.
Install or update SmartDescribe Pro.
Confirm that the plugin activates without errors.
Open the relevant plugin settings.
Test an individual optimisation.
Test bulk optimisation with a small product selection.
Verify that the expected alt text is saved.
Check the WordPress error logs.
Test the public product page.

A successful activation is only the first compatibility check. The actual optimisation workflow must also be tested.

4. How Can Developers Diagnose API Failures?

When an optimisation request fails, determine whether the failure originates from the plugin, the AI provider, or the hosting environment.

Check the provider configuration

Verify that:

The correct provider is selected.
The API key is valid.
The configured model is supported.
The account has access to the requested service.
Usage limits and billing arrangements are sufficient.

Inspect the response

If the plugin exposes an error message or diagnostic log, record the relevant details.

Depending on the provider and implementation, an API failure may involve:

Authentication.
An invalid model identifier.
Rate limiting.
Usage quotas.
Invalid request parameters.
Network errors.
Temporary service failures.
A response that the plugin cannot interpret.

Record the provider’s status code and error message where available.

Do not assume that every HTTP error means the API key is invalid. Different response codes can indicate different problems.

Check the timing

If requests fail intermittently, record when they occurred and whether other products succeeded at the same time.

This information can help distinguish a temporary provider problem from a persistent configuration error.

5. What Do Common HTTP Status Codes Mean?

The following table provides general guidance for diagnosing HTTP responses. The precise meaning depends on which service returned the response and the details of the request.

HTTP status	General meaning	Suggested investigation
400	Bad request	Check request parameters, model identifiers, and payload formatting
401	Unauthenticated	Check API credentials and authentication configuration
403	Forbidden	Check account permissions, key restrictions, and model access
404	Resource not found	Check the endpoint, model identifier, and API route
408	Request timeout	Investigate request duration and network reliability
413	Request too large	Check request payload or image size limits
429	Too many requests or quota restrictions	Check provider limits, usage, and billing
500	Internal server error	Determine whether the error came from WordPress or the external provider
502	Bad gateway	Investigate gateway, proxy, or upstream service errors
503	Service unavailable	Check temporary provider or hosting service disruptions
504	Gateway timeout	Investigate upstream response time and server timeout limits

These are general HTTP interpretations, not a guarantee that SmartDescribe Pro will display every status code directly.

Important diagnostic distinction

A 404 returned by an AI provider is not necessarily the same as a 404 returned by the WordPress website.

Always establish which endpoint returned the error before deciding what to change.

6. How Should Developers Investigate a Failed API Request?

Use a controlled sequence.

Step 1 — Reproduce the problem

Use one suitable product and record the time of the failed request.

Step 2 — Record the configuration

Document the selected provider and model without exposing the API key.

Step 3 — Capture the error

Record the HTTP status code, provider error message, and relevant request identifier if one is available.

Step 4 — Check the provider

Review the provider’s dashboard and service-status information.

Step 5 — Check server connectivity

If the provider reports no issue, investigate whether the WordPress server can make the required outbound HTTPS requests.

Step 6 — Check the plugin implementation

Review the installed version’s API integration and error-handling logic if you have the appropriate development access.

Step 7 — Test again

After changing one relevant setting, repeat the same test and compare the results.

Avoid making several configuration changes at once. Doing so can make it harder to identify the cause.

7. How Can Developers Check WordPress Errors?

WordPress and PHP logs can reveal errors that are not shown in the SmartDescribe Pro interface.

WordPress Site Health

Open:

WordPress Dashboard → Tools → Site Health

Review the available information and status reports.

Hosting logs

Depending on the hosting provider, logs may be available through the hosting control panel or a supported server-management interface.

Look for entries matching the time of the failed optimisation.

Useful information includes:

PHP fatal errors.
PHP warnings related to the operation.
Memory exhaustion.
Request timeouts.
Permission errors.
Failed network requests.
Errors involving WordPress HTTP API functions.

A warning in a log does not necessarily mean it caused the optimisation failure. Correlate the message with the timing and behaviour of the failed operation.

Debug logging

A developer may enable WordPress debug logging temporarily when additional information is required.

On a production website:

Avoid displaying PHP errors to visitors.
Restrict access to diagnostic logs.
Remove or protect sensitive information.
Disable unnecessary debugging when the investigation is complete.

Do not publish raw logs containing credentials, private paths, customer information, or authentication tokens.

8. What Should Developers Check When Alt Text Is Not Saved?

When the AI returns a valid result but the alt text does not change, investigate the saving stage separately from the generation stage.

Questions to investigate

Did the AI request complete successfully?
Did the plugin receive a usable text result?
Did any validation step reject or modify the result?
Did the saving operation execute?
Did WordPress report a saving error?
Is the correct image being inspected afterward?
Is another component changing the value after it is saved?

WordPress image metadata

In a typical WordPress installation, an image uploaded to the Media Library is represented by an attachment post. Its alternative text is commonly stored in attachment metadata under the key:

_wp_attachment_image_alt

This is a general WordPress implementation detail, not a guarantee that every image or every SmartDescribe Pro workflow uses the same storage path.

When investigating a specific installation, verify the actual attachment and its metadata rather than assuming the product ID and image attachment ID are identical.

Recommended approach

Use WordPress-supported APIs and the installed plugin’s actual implementation when inspecting or modifying attachment metadata.

Avoid directly editing the database as a first response. An incorrect update can affect the wrong attachment or create inconsistencies.

9. How Can Developers Distinguish Product IDs From Image Attachment IDs?

WooCommerce products and WordPress images are separate records.

A product may reference one or more image attachments, but the product ID is not necessarily the same as the attachment ID.

This distinction matters when diagnosing alt text.

For example:

The product record identifies the WooCommerce product.
The featured image reference identifies an image attachment.
The attachment stores image-related information.
The public product page may render that image through theme or plugin code.

When investigating an unexpected alt text value, confirm the exact attachment being used.

Do not assume that changing metadata on a product record will update the image’s alternative text.

Similarly, changing one image attachment may affect other locations on the website if the same image is reused across multiple products or pages.

10. How Should Developers Investigate Bulk Processing Problems?

Bulk optimisation introduces additional variables compared with processing a single product.

Potential causes include:

Request volume.
Provider rate limits.
PHP execution limits.
Server memory limits.
Interrupted browser requests.
Network interruptions.
Errors affecting particular products or images.
Background-processing failures, if the installed implementation uses background jobs.

Diagnostic sequence

Test an individual product.
Test a small group of products.
Compare successful and failed products.
Check provider usage and rate limits.
Review server logs at the time of the failure.
Determine whether the problem follows particular products or occurs after a similar amount of processing.
Repeat a controlled test after making one relevant change.

If failures consistently occur after a similar duration, investigate timeouts and request handling.

If the same product fails regardless of batch size, inspect its image, metadata, and eligibility for optimisation.

If failures occur intermittently across different products, investigate provider limits and network reliability.

Do not assume that the installed version uses a particular queue, batch size, or background-processing library without checking the code.

11. How Should Developers Investigate Scheduled Processing?

If scheduled optimisation is available in the installed version, verify that the scheduling mechanism is configured and running as expected.

WordPress commonly uses its scheduling system, WP-Cron, for time-based tasks. Some hosting environments also use a system cron job to trigger WordPress scheduled events.

However, the actual scheduling mechanism used by SmartDescribe Pro must be confirmed from the installed version.

Investigation checklist

Is scheduling enabled in the plugin?
Is the intended schedule saved?
Are the relevant products eligible for processing?
Are scheduled tasks running on the website?
Is the hosting environment restricting execution?
Are provider requests succeeding when the task runs?
Are there relevant PHP or server errors?

Recommended testing

Compare a manual optimisation with the scheduled workflow.

If manual optimisation succeeds but scheduled processing fails, focus on scheduling, permissions, background execution, and the context in which the task runs.

If both workflows fail, investigate the common components first, such as the provider configuration and image data.

Do not create additional scheduled jobs or change cron configuration until you understand how the installed plugin handles scheduling.

12. How Can Developers Investigate Plugin Conflicts?

Conflicts may occur when multiple plugins or themes modify product data, image metadata, API requests, or administrative behaviour.

Common areas to examine

Image optimisation plugins.
Media library management tools.
SEO plugins.
Caching and performance plugins.
Security plugins.
Custom WooCommerce extensions.
Theme or page-builder image rendering.
Custom code in a child theme or site-specific plugin.

Recommended conflict test

Reproduce the problem on a staging site.
Record the active theme and plugins.
Confirm that SmartDescribe Pro works under the baseline configuration.
Reintroduce other components methodically.
Repeat the same test after each change.
Record the first change that causes the problem to return.

This approach provides stronger evidence than disabling several plugins at once.

Do not perform disruptive conflict testing on a live store without a suitable backup and recovery plan.

13. How Should Developers Investigate Caching Issues?

Caching can complicate diagnosis when the saved image metadata differs from the content displayed on the public website.

Potential caching layers include:

Browser cache.
WordPress page cache.
Object cache.
Hosting-level cache.
Content delivery network cache.
Cached page-builder or generated markup.

Diagnostic sequence

Inspect the saved alt text in WordPress.
Confirm the image attachment being used.
Inspect the rendered image markup on the public page.
Compare the saved value with the rendered alt attribute.
Clear the relevant cache if the output is stale.
Retest the page.

If the database contains the correct value but the rendered HTML contains a different value, investigate the component generating the HTML.

If the rendered HTML contains the correct value but a browser or assistive technology behaves unexpectedly, investigate the page markup and the accessibility context separately.

Caching should not be assumed to be the cause until the saved data and rendered output have been compared.

14. Can SmartDescribe Pro Be Diagnosed Through WP-CLI?

WP-CLI is a command-line interface for managing WordPress installations. Developers may use it to inspect plugin status, WordPress versions, and relevant site information.

For example, a developer with appropriate server access may run:

wp plugin list

This displays installed plugins and their status.

To check the WordPress version, a developer may run:

wp core version

These commands are general WP-CLI commands. They do not provide a SmartDescribe Pro-specific diagnostic report.

Before running commands:

Confirm that you are working in the correct WordPress installation.
Use an account with appropriate permissions.
Follow the hosting provider’s supported procedures.
Avoid running commands that modify production data unless the change is understood and authorised.

Do not assume that SmartDescribe Pro provides a dedicated WP-CLI command unless that functionality is documented in the installed version.

15. Should Developers Modify the Plugin’s Source Code?

Direct source-code modifications should not be the first troubleshooting step.

Changing plugin files can:

Introduce PHP errors.
Alter expected behaviour.
Create security problems.
Make future updates overwrite the changes.
Make support investigations harder because the installation no longer matches the distributed release.

If a code-level change is required:

Back up the website.
Reproduce the problem on staging.
Review the relevant source code.
Identify the cause before changing the implementation.
Make the smallest appropriate change.
Test individual and bulk workflows.
Check logs for new errors.
Document the change.
Plan how the modification will be maintained through future updates.

Where possible, use documented WordPress hooks or an appropriate site-specific extension instead of editing vendor plugin files.

Do not assume SmartDescribe Pro exposes a specific hook or filter without checking its source code or official developer documentation.

16. Security Considerations for Developers

SmartDescribe Pro interacts with product information and external AI services. Diagnostic work should protect both the store and its customers.

API credentials

Keep API keys out of public code repositories.
Do not expose keys in browser-side JavaScript.
Avoid writing complete keys to logs.
Restrict access to configuration and diagnostic information.
Rotate a key if it has been exposed.

WordPress permissions

When reviewing custom code or plugin behaviour, confirm that administrative actions require appropriate capability checks.

Input and output handling

Code-level changes should follow WordPress security practices, including suitable validation, sanitisation, escaping, and request verification where applicable.

Diagnostic data

Remove unnecessary customer information and credentials before sharing logs or screenshots.

Only collect the information required to investigate the problem.

Important: These are general WordPress security recommendations. They should not be interpreted as a claim that a particular SmartDescribe Pro release implements a specific security mechanism without verification.

17. Performance and Resource Considerations

AI optimisation involves external requests, so performance depends on more than the WordPress server alone.

Relevant factors may include:

Number of products being processed.
Number and size of images involved.
Provider response times.
API usage limits.
Network reliability.
PHP memory and execution limits.
The installed plugin’s request and processing strategy.

Recommended practices

Test new settings on a small selection of products.
Process large catalogues in manageable groups where appropriate.
Avoid unnecessary repeated optimisation.
Monitor API usage and costs.
Check server logs when operations fail consistently.
Schedule large operations during suitable maintenance windows if the installed version supports scheduling.

Do not increase server limits indiscriminately. First establish whether a server limit is actually responsible for the problem.

18. What Information Should Be Included in a Developer Escalation?

When a problem requires developer investigation, provide enough information to reproduce it without exposing confidential data.

Include:

Environment

SmartDescribe Pro version.
WordPress version.
WooCommerce version.
PHP version.
Hosting environment, if relevant.
Active theme and relevant plugins.

AI configuration

Provider.
Model.
Whether the API account is active.
Relevant usage or quota information.
Error status code, if available.

Reproduction

Exact steps.
Product and attachment IDs where appropriate.
Whether the problem occurs with one product or many.
Whether individual optimisation works.
Whether bulk or scheduled optimisation fails.

Diagnostics

Exact error message.
Relevant log entries.
Timestamp and time zone.
Recent software changes.
Tests already performed.

Security

Remove API keys, passwords, access tokens, and unnecessary customer data before sharing the report.

If the problem involves a specific product or image, use the relevant IDs where appropriate rather than sending an entire database export.

19. Developer Troubleshooting Matrix

Symptom	Likely area to investigate	Useful diagnostic step
API authentication failure	Credentials or provider account	Verify the key and provider configuration
Model-related error	Model identifier or account access	Check provider model availability
HTTP 429	Rate limits or quota	Review provider usage and retry policy
HTTP 404	Incorrect resource, endpoint, or model	Identify which service returned the response
Generated text is not saved	Saving logic, permissions, or validation	Compare the API result with the saved attachment metadata
Incorrect image is updated	Product-to-attachment mapping	Verify product and attachment IDs
Bulk operation stops	Batch handling, limits, or provider errors	Compare individual and small-batch tests
Scheduled operation fails	Scheduling or background execution	Compare scheduled and manual runs
Dashboard error	PHP, permissions, or JavaScript	Inspect browser and server diagnostics
Correct saved value, wrong public output	Theme, markup, or caching	Compare attachment metadata with rendered HTML
Intermittent failures	Network, provider, or resource limits	Correlate timestamps with logs
Failure begins after an update	Compatibility or regression	Reproduce on staging and compare versions

These are investigation starting points, not definitive diagnoses.

20. Frequently Asked Technical Questions

Does successful plugin activation prove compatibility?

No. Activation confirms only that the plugin can be loaded sufficiently to activate. The relevant settings, API calls, saving operations, and public output must also be tested.

Does an HTTP 401 always mean the API key is wrong?

It generally indicates an authentication problem, but the exact cause depends on the service returning the response. Check the endpoint, credentials, and authentication configuration.

Does an HTTP 404 always mean the AI model does not exist?

No. The error may come from the provider, a proxy, the WordPress website, or another endpoint. Establish which service returned it.

Why does the API return text but WordPress does not show the change?

The problem may occur during validation, saving, attachment selection, or public-page rendering. Compare the generated result, saved metadata, and rendered HTML.

Can increasing PHP memory fix bulk optimisation?

Only if memory exhaustion is contributing to the failure. Review the logs before changing resource limits.

Can I assume scheduled optimisation uses WP-Cron?

No. WP-Cron is a common WordPress scheduling mechanism, but the installed plugin’s implementation must be checked.

Can I write a script to update the alt text directly?

A developer can use WordPress-supported APIs to modify attachment metadata, but the script must identify the correct attachments and preserve existing data where appropriate. Test on staging and back up the site before running bulk modifications.

Should I share a full debug log with support?

Only when necessary and through an appropriate secure channel. Remove credentials, access tokens, customer information, and other sensitive details first.

Can every SmartDescribe Pro issue be diagnosed from the WordPress dashboard?

No. Some problems require access to hosting logs, the AI provider dashboard, or the installed plugin’s source code.

21. Final Recommendations

For advanced troubleshooting, separate the optimisation workflow into distinct stages: product selection, image identification, provider request, response handling, saving, and public display.

Test one product first, capture the exact error, and correlate it with the relevant WordPress, hosting, or provider logs. Use staging for conflict testing and code changes, and protect credentials throughout the investigation.

Avoid assuming that undocumented hooks, database keys, scheduled-task mechanisms, or diagnostic commands exist. Verify the actual installed version before making code-level changes.

The objective is to identify the failing component, reproduce the issue reliably, and make the smallest safe change that resolves it.