Documentation · Troubleshooting
Solve the right problem without creating a second one.
Start with the failed layer, preserve the exact error and confirm what already happened on WordPress before you repeat an action. This guide helps you diagnose SitePublisher AI safely and efficiently.
For SitePublisher AI Free and Pro · Never share keys, passwords or access tokens
Before you retry
Three checks prevent most troubleshooting mistakes
A failed screen message does not always mean the entire workflow failed. Text generation, image creation, local queue storage and remote WordPress publication are separate steps.
Capture the exact moment
Copy the complete error message and note the date, time and timezone. Record the page, button or queue action you used, plus the SitePublisher AI edition and build shown in the interface.
See the support checklist →Check both WordPress sites
For remote publishing, inspect the central SitePublisher AI website and the destination website. Search the destination by the exact title and check Published, Scheduled, Draft and Trash.
Prevent duplicate publication →Open Health and Logs
Use the SitePublisher AI dashboard links for Health checks and Logs. Fix a required Health failure first, then reproduce the problem once and inspect the matching log time.
Run the technical checks →Health checks
Fix required environment failures before testing the workflow again
A required failure can prevent SitePublisher AI from starting completely. The Health page shows the status and a short explanation for every check.
Required environment
Ask the hosting provider to change the PHP version when this check fails.
Create a backup and update WordPress through the normal maintenance process.
cURL, JSON, Mbstring and OpenSSL must be available. Missing extensions are hosting-level issues.
Plugin services and storage
If a required class cannot load, reinstall the same official package after making a backup. Do not merge plugin folders manually.
Both directories must exist and be writable. Your host can correct file ownership or permissions without exposing credentials.
A detected legacy Marketing Hub installation is informational during migration; it is not itself a required failure.
Who should fix it?
Environment errors belong with the hosting provider.
Send the host the failed check name and message. Never send a WordPress password, OpenAI key or Application Password with that request.
Logs
Reproduce once, then isolate the matching event
The Logs page can filter by file, severity, source and text. Use the smallest relevant time window and share only the lines needed to explain the failure.
Reproduce one controlled time
- Clear unrelated screen messages before the test
- Perform the failing action only once
- Write down the exact local time and timezone
- Keep the visible error message for comparison
Narrow the log view
- Choose the relevant log file and recent entry limit
- Start with warning, error and critical levels
- Search by source, article title fragment or error text
- Use 15, 30 or 60 second auto-refresh only while testing
Open details safely
- Use View details for the matching event context
- Include only the useful timestamp, source and message
- Redact domains or identifiers when they are not relevant
- Never copy keys, passwords, tokens or authorization headers
Match the symptom
Use the checklist for the step that actually failed
Resolve the underlying cause before selecting Retry. A successful article, image or remote post should not be generated a second time merely to repair a later bookkeeping error.
No article or AI image
Open OpenAI API Settings and confirm the key is configured. Check the OpenAI account for billing, available credits or usage limits. Authentication and quota errors require a key or account fix; rate limits, timeouts and temporary server errors may be retried after waiting.
Open the API guide →Website or categories will not connect
Confirm the HTTPS address, WordPress REST access and dedicated Application Password. The authenticated account must be able to edit posts. For a 403 or an empty category list, also check the separate hosting WAF, even if you removed the WordPress security plugin. Follow the HTTP 403 and hosting firewall checklist.
Check the connection guide →Remote publication fails
Read the returned HTTP message before changing anything. Confirm the destination account can create the requested status, and that the REST API accepts posts and media. If stored credentials can no longer be decrypted, enter a new Application Password in Website Settings.
Check for an existing result first →A selected or generated image fails
Confirm the Media Library attachment still exists and its file is readable. SitePublisher AI rejects unreadable, unsupported or oversized image data. In a queue job, an image failure preserves the completed article and moves it to review instead of discarding the text.
Review image choices →Bulk Automation stops or needs attention
Check whether the process is deliberately stopped, waiting, processing, in review or failed. Read the row-level error. Resume a stopped process only when ready; Retry is for a resolved failure. Deleting a recoverable queue record does not remove published WordPress posts or media.
Diagnose the queue →A scheduled post is late
Compare the central timezone, destination timezone and approved UTC preview. Allow the ten-minute recovery grace period, then use Check & recover schedules. Also inspect WordPress Site Health for late events or failed loopback requests.
Open scheduling reliability →Connection troubleshooting · HTTP 403
When a hosting firewall blocks your website connection
This guidance applies to remote website connections in SitePublisher AI Pro. Free publishes on the current website; these checks do not add remote website access to Free.
A 403 does not automatically mean a wrong password
You may see “Credential verification returned HTTP 403” before any categories appear. SitePublisher AI first verifies the authenticated WordPress user and editing permission, then retrieves categories. A firewall can block that first request before WordPress checks the credential.
An HTML error page suggests a server or security layer, but does not identify the cause by itself. Match the failed request to the hosting logs. A working public category page or a successful connection from another service does not prove that this connection is allowed.
Hosting security is separate from a WordPress plugin
Defender is a WordPress security plugin. A hosting Web Application Firewall (WAF) can filter requests before they reach WordPress. Removing Defender does not switch off the host’s separate WAF.
Two websites can therefore behave differently even with the same WordPress plugins and SitePublisher AI settings. Check each destination’s hosting firewall configuration rather than assuming that settings are identical across your websites.
Find the exact blocked request
On WPMU DEV, open the destination in The Hub and check Hosting → Logs → WAF. Firewall settings are under Hosting → Tools → Web Application Firewall; labels may vary.
Match the test time and timezone, request path, source IP and rule ID. The verification route is /wp-json/wp/v2/users/me, with context=edit and the requested user fields. Its User-Agent is “SitePublisher AI credential verification”.
Ask the host for a targeted correction
Send hosting support the matched rule ID, request time, destination, path and source IP. Ask them to review the legitimate authenticated request and apply the narrowest suitable exception for that destination, rule and request. WordPress authentication and permission checks must remain active.
If IP allowlisting is appropriate, the relevant address is the outgoing server IP of the central SitePublisher AI installation. An “Allowlist my IP” button may instead select your browser’s internet address. The host should confirm the actual source IP and whether it is shared or changes.
Saving an IP allowlist entry is not proof that the request is allowed. If it still fails, ask support to check why the exception did not apply. Do not keep deleting and recreating the saved website connection.
Known WPMU DEV rule: 225170
In a confirmed support case, rule 225170 blocked the user-verification request and reported “Sensitive Information Disclosure Vulnerability in WordPress 4.7 (CVE-2017-5487)”. That text identifies the rule; it does not establish that the website runs WordPress 4.7 or has been compromised.
In that case, adding the source IP did not restore category retrieval, while temporarily switching off the hosting WAF did. This isolated the hosting firewall as the blocking layer. Why the IP exception did not apply remained unresolved; other websites without that WAF enabled were unaffected.
After the host’s correction, make sure the WAF is enabled and run Refresh all categories again. Category retrieval does not prove that post or media creation works: check one reviewed draft and its image before starting a bulk run.
References: WPMU DEV guidance on blocked REST requests and WAF logs · WordPress Application Passwords and authentication troubleshooting.
Important before republishing
WordPress may already contain the article or media.
A remote request can succeed before a later local status, report or link-record update fails. Search the destination website by the exact title and inspect Published, Scheduled, Draft and Trash before sending the article again.
Scheduling reliability
Understand what automatic recovery will and will not change
SitePublisher AI Pro verifies approved automatic WordPress schedules after the planned time. It protects deliberate changes made directly on the destination.
Automatic recovery can
- Check the remote post after the schedule plus ten minutes
- Recognize a post that published normally
- Publish a post that is still genuinely marked as future
- Show recovered, pending or recovery-failed status in the queue
Automatic recovery will not
- Publish before the approved time and grace period
- Override a post moved to Draft, Private or Trash
- Undo a later publication date set on WordPress
- Recover a post without a valid recorded remote post identifier
Prepare a support request
Send enough context to reproduce the issue—without sending access
A focused report is faster to investigate than a complete log export. Include one problem, one controlled attempt and the smallest useful set of technical details.
Include these details
SitePublisher AI Free or Pro, build number, WordPress version and PHP version.
The page, button and destination involved, plus what you expected to happen.
The full sanitized error, exact time and timezone, and whether a remote post or image already exists.
One relevant screenshot and one matching log event. Include a queue or article identifier only when useful.
Never include these secrets
Support can diagnose authentication without seeing the secret value.
Do not paste WordPress, hosting, database or email credentials.
Redact bearer tokens, session cookies, recovery codes and request headers.
Never send card details or unrelated personal customer data in a diagnostic request.
Still blocked?
Send the prepared report through the Contact page.
Choose a clear subject, describe one reproducible problem and mention the checks you already completed.
Troubleshooting FAQ
Safe answers before you change anything
Keep the successful parts of a workflow intact and change only the layer that actually failed.
Should I reinstall the plugin first?
No. Start with Health checks and Logs. Reinstall only when the autoloader or package files are incomplete, and use the same official package after making a backup.
Should I keep pressing Retry?
No. Read the row-level error and correct its cause first. Repeated attempts can spend additional API credits or create duplicate remote content.
What if the article exists on the destination?
Do not republish it. Save the post URL and report the later local error so the remaining status or bookkeeping problem can be investigated separately.
Can I send a key or password so support can test?
No. SitePublisher AI support should not need your secret values. Replace a compromised credential immediately with the provider that issued it.
What if the entire WordPress website is unavailable?
Contact the hosting provider first. A full outage, missing PHP extension, filesystem permission failure or server cron problem requires hosting-level access.
Why was a scheduled article left untouched?
The recovery service respects deliberate changes on WordPress. A post moved away from the future state or rescheduled for later is not forced live.
Continue the documentation
Next: updating and managing a license
Learn how the commercial edition, license status and secure product updates fit into your SitePublisher AI installation.