Troubleshooting

Fixes for common problems: an AI app that cannot connect, 401, 403 and 429 errors, blocked headers, permission errors, rescue mode, license and backups.

Updated 30 October 2026

Most problems come down to a key that did not arrive, a request that a firewall or setting refused, or a permission that the connection does not have. Find the message you see below. The error texts are the ones your site sends.

Find your problem#

You see	Go to
An app cannot connect, or you see 401, 403, 429 or 503	The app cannot connect
"Permission denied"	Permission denied errors
A message about your license or plan	License problems
Claude or ChatGPT sign-in fails	Sign-in problems
The site shows a critical error	Fix a critical error
A backup fails	Backups

Where to look first#

PowerWP AI › Activity lists every request. Set Channel to Security, or Status to Denied or Errors (all), to see refused requests, with the reason in the message. See Activity log.
PowerWP AI › Changes shows what was changed, by which connection, and whether it can be rolled back. See Change log and undo.
PowerWP AI › Dashboard, card Environment checks (select Run checks), tests HTTPS, whether the endpoint and both key headers reach WordPress, the loopback requests used for health checks, private storage and the rescue loader.
PowerWP AI › Help repeats the setup steps for each AI app and a short troubleshooting list.

The app cannot connect#

Messages from your site#

Message	What it means	What to do
401 "Authentication required"	The key did not reach WordPress.	Make sure the app sends the `X-WPAI-Token` header. See the next section.
401 "The token is not valid"	The key is wrong, incomplete, or belongs to a connection that no longer exists.	Copy the setup step again. A key cannot be shown twice: if you lost it, revoke the connection and create a new one.
401 "This credential has been revoked"	The connection was revoked.	Create a new connection.
401 "This token expired on …"	The connection's expiry date has passed.	Create a new connection and choose a longer expiry under More options. Expired connections cannot be edited.
403 "This endpoint only accepts HTTPS connections"	The request used `http://`.	Use the `https://` address. Behind a proxy that ends HTTPS, turn on Trust X-Forwarded-Proto.
403 "Your IP address is not in this credential's allow-list"	The connection has an IP allow-list and the request came from another address.	Edit the connection under PowerWP AI › Connections and add the address, or clear the list.
403 "Management keys cannot be used by AI apps"	A key that is not a connection key was used.	Create a connection for the app under PowerWP AI › Connections and use its key.
403 "The WordPress user attached to this credential no longer exists or is not an administrator"	The person who created the connection was deleted or lost the administrator role.	Create a new connection while signed in as an administrator.
403 "Forbidden: Origin not allowed"	A browser-based client on another website sent the request.	Use an app that connects directly. Desktop and command-line apps send no Origin header.
429 "Too many failed authentication attempts"	Too many wrong keys came from one IP address. By default 10 failed attempts lock the address for 15 minutes.	Fix the key and wait. The thresholds are under Settings › Connection security.
429 "Rate limit exceeded"	More than 240 requests in a minute (the default) from one connection.	Wait a minute, or raise Rate limit per key.
503 "AI access to this site is paused"	The AI access switch is off, or `WPAI_MCP_DISABLED` is set in `wp-config.php`.	Turn AI access back on with the switch in the header of any PowerWP AI screen (the pill reads AI off), or under Settings › General. If the constant is set, remove it.

The Authorization header is stripped#

Many hosts remove the Authorization header before it reaches PHP. This is common with Apache and FastCGI, some proxies and JWT plugins. That is why every PowerWP AI setup step sends the key in an X-WPAI-Token header instead.

If your app lets you choose the header, use X-WPAI-Token. If an app only has a bearer-token field, it sends Authorization: Bearer, which works only if your host passes that header on. The Environment checks test both headers and say which one arrives. If X-WPAI-Token itself is stripped, look at proxy and firewall rules that drop custom headers.

A firewall, Cloudflare or a security plugin blocks the requests#

Web application firewalls and security plugins, such as Cloudflare, Wordfence, Sucuri and Solid Security, and "disable REST API" plugins, can block /wp-json/wpai/v1/. The Environment checks then report an unexpected answer from the endpoint. Allow that path. PowerWP AI protects it with its own token check, rate limits, lockouts and IP allow-lists.

The address looks wrong behind a proxy#

Behind Cloudflare or another proxy, every request seems to come from the proxy, so IP allow-lists and lockouts do not work as expected. Choose the right Client IP source under Settings › Connection security. The screen shows what each header carries for your request. Choose a proxy header only if the site really is behind that proxy.

The app does not list your site#

Quit the app completely and open it again. Most apps read their MCP settings only when they start. In a JSON settings file, a missing comma or bracket stops the whole file, so copy the setup again if you are unsure. A connection that has not been used yet shows Setup steps in the list under PowerWP AI › Connections.

"Permission denied" errors#

A message such as Permission denied: this token lacks the "content" scope means the connection does not have a permission the task needs. The error names the missing permission as required_scope. Add it:

Open PowerWP AI › Connections and select Edit on the connection.
Choose a preset that includes the permission, or tick the permission under Permissions.
Select Save changes.

Name in the message	Permission in the plugin
`content`	Content & store data
`settings`	Settings & maintenance
`files`	Files
`database`	Database writes
`extensions`	Plugins & themes
`users`	Users
`backups`	Backups & restore
`sensitive`	Secrets

Add only what the task needs. Files, Database writes, Plugins & themes, Users and Backups & restore carry high risk, and Secrets is critical. See Permissions and presets.

Read-only mode and the Free plan#

If the message adds "the site is also in global READ-ONLY mode", or says the site "uses the PowerWP AI Free plan", more permissions will not help. Read-only mode limits every connection to reading: turn it off under Settings › General › Read-only mode. The Free plan lets apps read but not change: upgrade in My account › Licenses and select Check now on the License screen. See AI access switch and read-only mode.

Rescue mode is on#

If a plugin or theme crashes the site while WordPress starts a request from an app that connects with a key, rescue mode switches on by itself, usually for 30 minutes. AI requests then run without your other plugins and your theme, so your app can still read the error and undo the cause. Rescue mode changes only what your AI app sees: visitors keep seeing the crash until the cause is fixed. Tools that depend on another plugin cannot use it until rescue mode ends.

The PowerWP AI Dashboard shows Rescue mode as Active, with the reason and the end time. To end it:

Let your AI app find and undo the cause. Ask it to read the error log and roll back the last change.
Select Disable rescue mode on PowerWP AI › Dashboard, or ask the app to run rescue_mode with the action disable.

Only disable it once the problem is fixed. See Rescue mode and Fix a critical error.

License problems#

Message	What to do
"This is not a PowerWP AI license key"	Copy the whole key from My account › Licenses. It looks like `PWAI-XXXXX-XXXXX-XXXXX-XXXXX`.
"Could not reach powerwp.ai to check the key"	Your server could not make an outgoing HTTPS request. Check the host's firewall, then try again in a few minutes.
"Connecting an AI app needs a license"	Enter your key under PowerWP AI › License.
"Your … plan includes … AI connections, and … are in use"	Revoke a connection you no longer need, or upgrade.
"More permissions for an AI connection need an active license"	Activate a paid plan. A Free key allows read-only.
"Your Free plan lets AI apps read this site, not change it"	Choose Read-only, or upgrade. The key stays the same.
"Your license is suspended"	AI apps can read but not change anything. Contact support.
"This site's license key is not valid any more"	Enter a valid key.
"The license is not active on this site any more"	Activate the key again. Its seat may have been freed for another site.

After an upgrade, or after you subscribe again, the site picks up the change within a day. Select Check now to apply it at once. See Activate your license.

"Sign-in is not available on this site yet." Switch on Settings › Connection security › Sign-in for AI apps, or choose a permalink structure other than Plain under Settings › Permalinks in WordPress.
"This site runs on this computer." Claude and ChatGPT connect from the internet and cannot reach a local site. Use Claude Code or another app on the same computer.
"Administrators only." Sign in to WordPress as an administrator.
"Wrong return address" or "Unknown app." Start the connection again in the AI app.
"The sign-in has expired" or "This sign-in was ended." Connect the app again. Revoking the connection under Connections ends the sign-in at once.
Signed-in apps stop working. Switching Sign-in for AI apps off pauses every app that signed in. Switch it on again and they carry on.
Still no luck? Connect with a key instead: Claude Code or Codex.

Backups#

Backups are built on the server in small steps of about 20 seconds that pick up again if they are interrupted, so a short PHP time limit does not stop them. They move forward while the Backups screen is open or an AI app checks on them, and with WP-Cron. If WP-Cron is disabled, let a system cron call wp-cron.php.

A backup is too big or slow. Choose a database-only or files-only backup instead of a full one. Under Settings › Backups add folders to Excluded paths and lower Skip files larger than. Caches and other backup plugins' archives are already excluded.
"Another backup is still running." Wait for it, or cancel it on the Backups screen.
"Cannot write … (storage full or not writable?)" Free disk space and make the storage folder writable. The Environment checks warn when less than 1 GB is free.
"The PHP zlib extension is required for backups." Ask your host to enable zlib.
"Backup file missing on the server." The server copy is removed after you confirm the download, or when it expires (48 hours by default). Use your downloaded copy with Restore from your computer.
"Not enough disk space for this restore." Free the space the message names and try again.

See Backups and restore.

Still stuck?#

Write to [email protected] or use the contact form. Include the exact message, the AI app you use and what the Activity log shows for the request.

Requirements and compatibilityHosts, headers, proxies and firewalls.Activity logFind the request that failed.Permissions and presetsGive a connection what it needs.Contact supportQuestions about a problem or an order.