Skip to content

Latest commit

 

History

History
187 lines (123 loc) · 6.86 KB

troubleshooting.mdx

File metadata and controls

187 lines (123 loc) · 6.86 KB
title description
Support & Troubleshooting
Troubleshooting guides for Respira for WordPress, including MCP server connection issues, API key errors, page builder detection problems, and how to get direct support.

Getting Support

All Respira licenses include technical support:

  • Starter plan: Email support at word@respira.press
  • Agency plan: Priority email support at word@respira.press
  • WooCommerce add-on: Technical support included with €7/month subscription

Response time: Typically within 24 hours
Who responds: Mihai (founder), not a support bot
What to include: WordPress version, Respira version, error messages, what you were trying to do

Before contacting support, check this troubleshooting guide. Many common issues have quick solutions below.

We're here to help

Use this page to diagnose and resolve the most common Respira for WordPress issues, including MCP server errors, API key failures, page builder detection problems, and publishing or saving issues.

Quick Diagnostics

Before diving into specific issues, run these commands to check your setup:

# Test your connection
npx @respira/wordpress-mcp-server --test

# List configured sites
npx @respira/wordpress-mcp-server --list

# Re-run setup wizard
npx @respira/wordpress-mcp-server --setup

Recommended version baseline (March 2026)

  • Respira for WordPress: 4.2.0+
  • MCP server: 4.0.0+
  • WooCommerce tooling: plugin 4.2.0+, MCP 4.0.0+, Woo add-on 1.0.2+

If you are on older versions, upgrade first before deep debugging.

Gathering information for support

Before requesting support, gather the following:

  • Exact error messages shown in WordPress or in the MCP server console
  • Output from --test command
  • Your site URL, including protocol (https://)
  • Respira for WordPress plugin version
  • Whether the issue happens on a specific page, builder, or environment

Common issues

MCP server not connecting

Quick fix: Run the setup wizard again:

npx @respira/wordpress-mcp-server --setup

Other checks:

  • Check that Node.js 18+ is installed: node --version
  • Verify your config file exists at ~/.respira/config.json
  • Run npx @respira/wordpress-mcp-server --test to test your connection
  • Review the MCP server console output for runtime errors
  • Confirm your system firewall or host environment is not blocking local connections
  • Restart your AI assistant (Cursor, Claude Code, etc.) after configuration changes

MCP update hints appear in tool responses (respira_mcp_update)

This is informational, not a runtime failure.

  • Upgrade with: npx -y @respira/wordpress-mcp-server@latest
  • Restart your AI client after upgrade
  • Disable daily update checks with: RESPIRA_MCP_DISABLE_UPDATE_CHECK=1

API key not working

  • Confirm the key starts with respira_ or respira_site_ and has no extra spaces
  • Check that the API key is active in WordPress Admin (Respira → API Keys)
  • Ensure your site URL is correct and includes https://
  • Review the audit log in WordPress Admin for failed API requests
  • Verify the key has not expired or been revoked
  • Try generating a new API key

Page builder not detected

  • Confirm the intended page builder plugin is installed and active
  • Make sure the page or post was created with that builder
  • Some page builders require specific Respira license tiers
  • If detection still fails, check for JavaScript errors in the browser console
  • Try reading the page directly: Read page ID 123

Elementor 500 errors (URL control / ltrim() / inject failures)

If Elementor writes fail intermittently or return 500-level errors:

  • Upgrade Respira plugin to 4.2.0+
  • Upgrade MCP server to 4.0.0+
  • Re-run setup: npx @respira/wordpress-mcp-server --setup
  • Re-test: npx @respira/wordpress-mcp-server --test
  • Retry the same operation once after upgrade

Recent fixes include safer handling for link-control array payloads, stricter payload normalization, and cache invalidation on fallback save paths.

Changes not saving

  • If direct editing is enabled, confirm whether you chose live or duplicate in preflight
  • For duplicate edits, verify you're reviewing the duplicate
  • Ensure your WordPress account has permission to edit the page or post
  • Review the audit log for validation or publishing errors
  • Confirm that content validation is passing
  • If drafts are not updating, clear any server-level or plugin caching

Setup page is read-only after upgrade

This is expected in the 4.0 admin IA refresh.

  • Edit plugin controls in Respira → Settings
  • Use Setup → Health & Permissions as a readiness/status summary

Windows: 'npx' not recognized

If you see 'npx' is not recognized as an internal or external command:

  • Use the full path: C:\Program Files\nodejs\npx.cmd
  • Or install globally: npm install -g @respira/wordpress-mcp-server
  • Ensure Node.js is in your system PATH

Site URL mismatch

The site URL in your config must match exactly what WordPress reports:

  1. In WordPress Admin, go to Settings → General
  2. Copy the "WordPress Address (URL)" exactly
  3. Update dashboard-generated MCP config, or ~/.respira/config.json for manual mode
  4. Re-run npx @respira/wordpress-mcp-server --test

Helpful resources

FAQ

How do I know if the MCP server is running?

Run npx @respira/wordpress-mcp-server --test to check the connection. If successful, you'll see a confirmation message with your site details.

What should I do if edits are not appearing on my site?

First check whether you are editing a duplicate page (this is expected behavior). Go to Respira → Approve Edits in WordPress Admin to approve changes. Also verify user permissions and clear any caching layers.

Can I use Respira on a staging or local site?

Yes. Ensure the API key and site URL in ~/.respira/config.json match the environment you are using. For local development, the MCP server runs on your machine alongside the AI assistant.

How do I switch between multiple WordPress sites?

Use wordpress_switch_site in your AI assistant, or configure multiple sites in ~/.respira/config.json and use --list to see them.

What information should I include when contacting support?

Include your site URL, plugin version, output from --test command, a description of the issue, and any logs or exact error messages.

How do I contact support?

  • Email: word@respira.press
  • Use the account dashboard for license-specific support options

Direct support

Respira for WordPress is a commercial plugin with dedicated support. For direct assistance, contact the team using the channels above and include as much diagnostic information as possible.