Troubleshooting

Things go wrong. This page covers the most common AI Connector problems and how to fix them.

If your problem is not here, email support@axtolab.com. Include your WordPress version, plugin version, AI client, the visible error message, and what you tried. Do not send passwords, private API keys, Application Passwords, or full license keys.

Download or account issues

I completed checkout but cannot find the ZIP

Check:

1. The order confirmation page.
2. Your order email.
3. My Account → Downloads on Axtolab.com.
4. Spam or promotions folders for Axtolab emails.

If you still cannot find it, contact support from the same email address used at checkout.

I cannot find my license key

Check the order confirmation page and order email first. If you need help, contact support from the checkout email address and include the product name.

The download link opens a page instead of downloading the ZIP

Try:

1. Open the link in a normal browser window, not inside an email preview.
2. Sign in to your Axtolab account and use My Account → Downloads.
3. Try a different browser.
4. Contact support if the link still does not return a ZIP file.

Connection issues

”Failed to connect” when adding an OAuth connection

Symptoms: the OAuth authorize page either won’t load, fails with a redirect error, or returns an “invalid_client” error.

Common causes and fixes:

1. HTTPS is required in production OAuth flows. Check your site URL — if it starts with http:// (no S), enable HTTPS first. Local dev environments allowed HTTP, production isn’t.
2. Site URL mismatch. Go to Settings → General and check that WordPress Address (URL) and Site Address (URL) match what you’re actually using. A trailing slash difference can break OAuth redirects.
3. Rewrite rules. If permalinks are set to “Plain”, switch to a structured format (e.g. “Post name”) and re-save. AI Connector’s REST endpoints rely on rewrite rules.
4. Caching. Aggressive page caching can return a stale authorization response. Temporarily bypass cache for WordPress login and REST API requests during setup.
5. Security plugin blocking REST. Security plugins sometimes block WordPress REST API requests by default. Temporarily relax the rule or allow the connector’s WordPress REST requests.

”Authorization expired” on an existing connection

OAuth refresh tokens are valid until you revoke. If a connection still says “expired” after refreshing, it usually means:

• The connection was revoked elsewhere (check the audit log for a connection_revoked entry)
• The plugin was deactivated and reactivated, which clears OAuth state
• The site URL changed since the connection was created

Fix: revoke the broken connection and re-authorize from scratch. Old tokens won’t come back.

Tools not appearing in your AI client

My desktop client does not show Axtolab AI Connector

1. Check the client’s connector or MCP settings.
2. If you used a setup file or bundle, confirm it was imported into the client.
3. Restart the client. Some clients only load connectors at startup.
4. Return to AI Connector in WordPress and repeat the guided setup if needed.

Tools list is empty inside Claude

Connection succeeded but no tools show up:

• Capability set was too narrow. Check the connection’s permissions at AI Connector → Connections → [your connection]. If only the read group is enabled (e.g. the read_only preset), you’ll only see read tools — no wp_create_draft, wp_publish_content, etc.
• Plugin needs to be active. Deactivating the plugin disconnects all clients silently — they may still appear connected in Claude until restart but return empty tool lists.
• Rate limit hit during initial handshake. Check AI Connector → Settings → Rate Limits → Recent activity.

Tool execution errors

”rest_forbidden” or “Sorry, you are not allowed…”

The connection’s OAuth scope doesn’t permit the action. Two fixes:

1. Revoke the connection and re-authorize with broader scope. Note that scope can only widen by re-authorizing — there’s no in-place upgrade.
2. Check WP user capabilities. OAuth scope is bounded by the WP user that authorized the connection. If you authorized as an editor, you can’t grant manage_options even if you select that scope.

”Rate limit exceeded”

Too many requests per minute from the same IP or connection.

• Check whether multiple clients are sharing the same connection.
• Split busy clients into separate connections.
• Reduce broad prompts that ask the AI to inspect or edit too many items at once.
• Review the rate limit settings if your site has unusually high legitimate AI traffic.

”Yoast tools not registered”

Yoast SEO tools only appear when the Yoast plugin is active. If you’ve installed Yoast but tools are missing:

• Make sure Yoast is activated, not just installed
• Re-authorize the connection — tools registered after the connection was created don’t retroactively appear
• Check that your plan tier of Yoast (free vs Premium) supports the API endpoints AI Connector uses; the free plan is sufficient for all the tools we expose

Performance issues

Site is slow when an agent is connected

• Audit log is large. High-traffic sites can accumulate many connector log entries. If your version includes pruning controls, remove old entries you no longer need.
• Database indexes missing. A few WP setups (mostly older installs) need a manual index rebuild: run wp db optimize via WP-CLI.
• Hosting limits. Some shared hosts throttle aggressive REST API usage. Check with your host’s logs if you suspect this.

OAuth flow takes 10+ seconds

The OAuth flow does several round trips on first connection — initial discovery, authorize, token exchange. 10 seconds is at the upper edge of normal but not broken.

If it’s consistently 30+ seconds:

• DNS issues. Check your site’s external DNS resolution time
• Slow PHP startup. PHP-FPM with cold processes adds latency on first request
• Caching layer interfering with authorization. See the OAuth connection issues section above.

Plugin update issues

Plugin updated but Connections page is broken

After a plugin update, the connections page fails to load:

1. Deactivate and reactivate the plugin. This re-runs the activation hook which migrates the database schema if needed.
2. Check for PHP errors in WP debug log. Enable WP_DEBUG_LOG in wp-config.php, look at wp-content/debug.log.
3. Clear object cache. If you use Redis or Memcached: wp cache flush.

Existing OAuth tokens stopped working after update

Tokens are preserved across normal updates. If they break:

• Major version bump? Major versions sometimes require token re-issue (we’ll announce this in the release notes if so).
• Plugin reinstall instead of update? Reinstalling clears OAuth state. Use Update, not delete-and-reinstall.

Where to get help

If nothing here fixes your issue:

Email support@axtolab.com.

The most useful details are:

• Plugin version and WP version
• AI client and version
• The exact error message (screenshot or copied text)
• Steps to reproduce
• Whether this is production or staging
• Any relevant screenshot

Do not send passwords, private API keys, Application Passwords, or full license keys.