Skip to content
BuildPressBeta
Troubleshooting

Troubleshooting

Fix connection problems, understand why a command was rejected, and clear common build snags.

Most problems fall into three buckets: your AI client cannot reach the MCP server, a command was rejected even though the connection works, or a build looks slightly off after it ran. Each one has a short, specific fix below.

Connection problems

If your AI client cannot connect at all, the request is usually being blocked or rewritten before it reaches WordPress. The MCP server lives inside your own site at https://your-site.com/wp-json/buildpress/v1/mcp, and the transport is POST only. Work through this list.

  • A firewall or security plugin is blocking the request. Allow POST to /wp-json/buildpress/v1/mcp in plugins like Wordfence, Sucuri, or Cloudflare. The route is POST only, so a rule that allows only GET will not work.
  • Your host strips the Authorization header. Some hosts drop it before it reaches PHP, which breaks Application Password auth. Whitelist the Authorization header for /wp-json/buildpress/*.
  • A strict client rejects an incomplete SSL chain. Node clients such as Claude Code and Cursor can fail with UNABLE_TO_GET_ISSUER_CERT_LOCALLY when your certificate is missing intermediate links. Fix it by serving the full certificate chain. As a last resort, tick the SSL option when you generate the connection, which tells the bridge to skip certificate verification.
  • The REST API is disabled. Open https://your-site.com/wp-json/ in a browser. If that does not return JSON, a plugin or setting has switched the REST API off, and BuildPress cannot register its route until it is back on.
  • Application Passwords are unavailable. WordPress only offers Application Passwords over HTTPS or in a local/dev environment. On a plain HTTP production site you cannot create one, so the connection has no credentials to use.

Quick health check

There is a public status route at https://your-site.com/wp-json/buildpress/v1/status. Open it in a browser with no login. If it answers, WordPress and the BuildPress route are reachable, so the problem is on the client or auth side.

The next AI command was rejected

Sometimes the connection is fine but the next build command comes back rejected with a clear message. That is by design: BuildPress refuses the action instead of doing the wrong thing. Match the message to one of these causes.

  • MCP access is disabled. The Master Switch is off, so every request is rejected. Turn it on at BuildPress -> Connection and click Enable MCP Access.
  • Access Mode is Read Only on a write. The AI can read but the write was refused. Switch the Access Mode to Read + Write on the Connection page so the AI can actually build.
  • The site domain changed. MCP is locked to the domain it was enabled on. After a clone or a move, MCP is treated as disabled on the new domain, so re-enable it at BuildPress -> Connection to mint a fresh lock for the current URL.
  • The license is invalid or expired. Build tools pause until the license is active again. Renew or re-enter your key at BuildPress -> License. If the license server was only briefly unreachable, it clears on its own once the server responds.

Your data is safe

A paused license never deletes anything. Your widgets, Project Memory, project history, and audit log all live in your own WordPress database. Renewing reactivates instantly with no migration.

If you are not sure which one applies, ask your AI to check. Paste a prompt like this and let it read back the exact reason it was blocked.

Example prompttext
My last command was rejected. Read the error message you got back and tell me exactly why, then tell me which BuildPress setting I need to change.

Common build snags

These are small finishing issues that show up after a build runs. None of them mean the build failed. Each has a one-line fix you can hand to your AI.

  • A new menu does not appear. A menu only shows once it is assigned to a theme location. Your AI does this as part of building the menu, so if it is missing, ask it to assign the menu to a location.
  • A dynamic field renders empty. The field is there but its binding was never configured, so it has nothing to pull. Ask your AI to bind it to the right source (a post field, a custom field, or a query).
  • An archive 404s after a cache clear. The rewrite rules were dropped. Ask your AI to flush permalinks, which re-registers the routes for your custom post types.

Paste-ready prompts for the three fixes above:

Example promptstext
My Main Navigation menu isn't showing up. Assign it to the correct theme location. The price on my product cards is blank. Bind that field to the product's price. My /projects archive 404s after I cleared the cache. Flush the permalinks.

Let render verification catch it first

Your AI checks the live page after each write and reports pass, warn, or fail lines, including unresolved dynamic fields a plain HTTP 200 would miss. If a build report flags something, fix it before publishing.

Still stuck on setup? Re-check the steps in Connect your AI client, or review license states in Licensing.

Share