Troubleshooting

Find the message you see, or the thing that does not work, and follow the fix. The messages are quoted as the plugin shows them.

Connecting

OAuth is Blocked, or its checkbox is disabled

OAuth requires a secure connection. This site is served over plain HTTP and is not a local environment, so tokens would cross the wire in the clear.

The site must be on HTTPS. Two cases are easy to miss:

• The site is on HTTPS but sits behind a proxy or load balancer, and WordPress does not know. Fix the proxy settings in wp-config.php so that WordPress detects HTTPS.
• It is a development site on your own computer. Set its environment type to local:

define( 'WP_ENVIRONMENT_TYPE', 'local' );

Application Passwords are not available

Application Passwords are not available on this site. WordPress offers them on HTTPS sites and on local environments.

Put the site on HTTPS. If it already is, a security plugin or a line of code has switched Application Passwords off. Check under Users → Profile: when the Application Passwords section is missing, look for the setting that removed it.

“Connection unavailable” on the consent page

This site is not accepting OAuth connections.

MCP clients over OAuth is off, the main switch is off, or the site is not on HTTPS. Switch it on from the Connect tab.

“You cannot connect an application”

The account you are signed in with does not have the capability the tools require, manage_options by default. Sign in as an administrator and start the connection again.

“This connection request is not valid”

The application making this request is not registered with this site, or it asked to be sent to an address it has not registered.

The site no longer knows the application. A registration that was never approved is removed after seven days. Remove the server or connector in the client, add it again, and sign in.

“This request could not be confirmed”

The consent page was open too long before you clicked. Start the connection again from the client.

401 “You must be logged in to use Block Theme MCP tools.”

WordPress did not see credentials it accepts.

For a client that signed in through OAuth: the connection was revoked, it went unused for more than 30 days, or MCP clients over OAuth has been switched off. Switch it on if needed, then sign in again from the client.

For a client with an Application Password: WordPress never saw your Authorization header.

1. Build the header again on the Connect tab. It must be the login name, a colon and the Application Password, base64-encoded together.
2. If the header is right, your host or a proxy is removing it. On Apache, add this line to .htaccess, above the WordPress rules:

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

3. If that changes nothing, ask your host to pass the Authorization header through to PHP.

A host that removes the header breaks sign-in through OAuth too, because the OAuth token travels in the same header.

401 “The provided password is an invalid application password.”

WordPress saw the header, but the password in it is wrong or has been revoked. Create a new Application Password and build the header again. See Connect with an Application Password.

403 “MCP clients over HTTP are switched off in Settings → Block Theme MCP.”

The request used an Application Password while MCP clients over HTTP (Application Passwords) is off. Switch it on under Ways to connect, or on the Connect tab.

403 “This Origin is not allowed to use the MCP endpoint.”

The request came from a web page on another site. The endpoint accepts browser requests only from your own site’s address. Connect from the client itself, not from a page.

The command fails in the shell on a site with plain permalinks

With plain permalinks the endpoint contains a question mark: https://example.com/index.php?rest_route=/btm/v1/mcp. Keep the quotes the Connect tab puts around it when you copy the command.

Tools are missing or refused

The client lists fewer tools than you expect

• The group is off. Check Tool groups on the Settings tab, or the pills on the Tools tab.
• The tool is browser only: btm.request, btm.browse-navigate, btm.browse-current-url and btm.browse-open-tab are never offered to a remote client.
• The client has an old list. Reconnect it so it reads the list again.

A remote client that calls a tool from a group that is off gets “Unknown tool”, followed by the tool’s name.

“You do not have permission to use Block Theme MCP tools.”

The account lacks the capability the tools require, manage_options by default.

A group’s checkbox is disabled, or its pill says Unavailable

The reason is printed with it. The common ones:

Editing theme files requires the edit_theme_options and edit_themes capabilities. WordPress removes edit_themes when DISALLOW_FILE_EDIT or DISALLOW_FILE_MODS is enabled, and on a multisite network only a Super Admin holds it.

Remove DISALLOW_FILE_EDIT or DISALLOW_FILE_MODS from wp-config.php if you want agents to edit theme files. A security plugin may set them for you.

Editing Site Editor templates requires the edit_theme_options capability and an active block theme.

The active theme is a classic theme. The Theme row of the Status card shows Classic theme and names the groups that need a block theme.

For Write files and Run PHP, see Allow file writes or running PHP.

“Block Theme MCP tools are not enabled in any context (admin screens or front end).”

A browser agent or the tool inspector called a tool while both Admin screens and Front end are off. Switch one on under Ways to connect.

Writes that are refused

409: the file or template changed

The file has changed since it was read: expectedHash does not match the current contents. Read it again and retry with the new hash.

Someone, or another agent, changed the file after this agent read it. Nothing was overwritten. The agent reads the file again and tries again with the new hash. Templates give the same answer with “The template has changed since it was read”.

409: “Another change to this theme is in progress. Try again in a moment.”

Two writes to the same theme arrived at once. The agent tries again.

A revert is refused

One or more files changed after this change set, so nothing was reverted. See conflicts; revert again with force to overwrite them.

A file was edited after the change set was made. Look at the files it names. Reverting with force overwrites the later edits.

“A file already exists at that path. Use btm.theme-update-file to change it.”

btm.theme-create-file only makes new files.

A content replace is refused with a token message

This token is unknown, expired, already used, belongs to another user, or was issued for a different mode or replacements. Run a new dry run with exactly the mode and replacements you want, then pass its token.

The token from a dry run works once, for 15 minutes, with the same mode and replacements. The agent runs the dry run again.

Changes that do not show

A theme file was edited but the page looks the same

• A page cache or a CDN is serving the old page. Clear it.
• A version of the template saved in the Site Editor takes precedence over the file. The tools report this as templateOverride. Reset the saved version, or edit it with the Site Editor templates tools.

A destructive tool does not run in the browser

• “The user declined to run” means the prompt was answered with Cancel.
• “closed before a person could answer it” means the prompt was dismissed automatically, often because the tab was in the background. Bring the tab to the front and try again.

Still stuck

Write to [email protected] with the exact message, the client you use, and how it connects. Leave out passwords, tokens and the Authorization header.