Troubleshooting
The failures that actually happen, what each one means, and the one command that tests for them.
Most failures are one of four things, and three of them are on the WordPress side.
The site cannot be added
The REST API is blocked. Open https://example.com/wp-json/ in a browser. You should get
JSON. A 404, a login page or an HTML error means something on the site refuses REST requests —
usually a security plugin with a "disable REST API" option, or a host rule. Turn it off for
/wp-json/, or allow requests that carry an Authorization header.
The site is not on HTTPS. WordPress refuses to issue application passwords over plain HTTP
unless WP_ENVIRONMENT_TYPE is local. Fix the certificate first; nothing else will work.
The credential is rejected. Copy the password again from Users → Profile → Application Passwords. It is generated once and shown once. The username is the WordPress login name, not the display name and not the email.
Everything reads, nothing writes
The Authorization header is being stripped. Some Apache and FastCGI setups drop it before
PHP sees it, so every request arrives unauthenticated and WordPress answers with the
permissions of a logged-out visitor.
The site health check tells the two apart. With a real application password in the request,
invalid still proves the header arrived and only missing means it was stripped.
The connector is read-only. Without the write scope the whole connection is built read-only and no write tools are registered at all. Ask for site information; it reports the read-only state.
The credential's role is too small. Design, template, menu and navigation tools need
edit_theme_options, an administrator capability. An Editor account cannot do them, and the
error says which capability is missing.
The assistant cannot see a site I added
Reconnect the connector. ChatGPT and claude.ai capture the tool list when the connection is made, and the list of sites is part of it. In ChatGPT, open the connector and press Refresh. In Claude, reconnect it.
Why this matters
Nothing is broken when this happens, and nothing in the error says "reconnect". The site list is a closed enum built per connection, which is exactly what stops a model naming a site you never registered — so it cannot also be rebuilt mid-conversation.
"Free allowance used on this site"
The Free tier includes ten changes on a site, once. The eleventh returns that message with a link. Reads keep working, and everything already done stays done. See plans and actions.
Ask the tools first
wp_site_info is built for this. It reports the WordPress version, whether the theme is a
block theme, the post types and taxonomies that exist, what the credential may do, and every
tool unavailable on that site together with the step that would enable it. Ask for it before
guessing.
Running the npm package locally, doctor does the same from the command line:
npx wpreef doctorIt validates the config, probes every site, and prints what each credential can do. The three
things it tests are the three above: HTTPS, the REST API reachable, and the Authorization
header reaching PHP. Each failure prints its own fix.
Undoing a change
Every write returns a restore handle, and undo goes through WordPress's own revisions. Ask the assistant to restore the revision it named. The audit log in your dashboard lists what changed and when, for 90 days — it records the change, never the content.