Ultimate Elementor MCP

# 🔧 Ultimate Elementor MCP - Troubleshooting Guide Solutions to common issues and problems. --- ## 📋 **Table of Contents** - [Connection Issues](#connection-issues) - [Configuration Issues](#configuration-issues) - [Elementor Issues](#elementor-issues) - [File Operation Issues](#file-operation-issues) - [Performance Issues](#performance-issues) - [Permission Issues](#permission-issues) --- ## 🌐 **Connection Issues** ### **Problem: Cannot Connect to WordPress** **Symptoms:** - Connection timeout errors - "Failed to fetch" errors - Network errors **Solutions:** 1. **Verify WordPress URL** ``` ✅ Correct: https://your-site.com (no trailing slash) ❌ Wrong: http://your-site.com/ (trailing slash) ❌ Wrong: your-site.com (missing protocol) ``` 2. **Check REST API Availability** - Visit: `https://your-site.com/wp-json/` - Should see JSON response - If 404, REST API might be disabled 3. **Test Application Password** ``` Use the test_wordpress_connection tool to diagnose ``` 4. **Check Firewall/Security** - Some hosts block REST API by default - Check with your hosting provider - Whitelist your IP if needed 5. **Verify HTTPS** - WordPress 5.6+ requires HTTPS for Application Passwords - Use HTTPS in your `WORDPRESS_BASE_URL` --- ### **Problem: Authentication Failed (401/403 Errors)** **Symptoms:** - "Unauthorized" errors - "Invalid credentials" messages - 401 or 403 HTTP status codes **Solutions:** 1. **Check Application Password Format** ```env ✅ Correct: xxxxxxxxxxxxxxxxxxxx (no spaces) ❌ Wrong: xxxx xxxx xxxx xxxx xxxx xxxx (spaces) ``` 2. **Verify Username** - Use actual WordPress **username**, not email - Check spelling carefully 3. **Regenerate Application Password** - Delete old application password in WordPress - Create a new one - Update your configuration 4. **Check User Role** - Ensure user is Administrator or Editor - Contributor and Subscriber may have limited permissions 5. **Test with cURL** ```bash curl -u "username:applicationpassword" https://your-site.com/wp-json/wp/v2/posts ``` --- ### **Problem: Page Not Found (404 Errors)** **Symptoms:** - "No route was found" errors - 404 status codes when accessing pages **Solutions:** 1. **Verify Page/Post ID** ``` List all pages to find the correct ID ``` 2. **Check Content Type** - Use `get_pages` for pages - Use `get_posts` for posts - Don't mix them up 3. **Verify REST API Endpoint** - Pages: `/wp-json/wp/v2/pages/[ID]` - Posts: `/wp-json/wp/v2/posts/[ID]` --- ## ⚙️ **Configuration Issues** ### **Problem: No MCP Tools Available** **Symptoms:** - "No tools found" message - Empty tool list - MCP server seems inactive **Solutions:** 1. **Check WordPress Credentials** ```env # All three are REQUIRED: WORDPRESS_BASE_URL=https://your-site.com WORDPRESS_USERNAME=your-username WORDPRESS_APPLICATION_PASSWORD=xxxxxxxxxxxxxxxxxxxx ``` 2. **Verify MCP Mode** ```env MCP_MODE=full # Options: essential, standard, advanced, full ``` 3. **Check Server Logs** - Look for "WordPress environment variables not found" warning - Server will start with limited functionality without credentials 4. **Rebuild Project** ```bash npm run build ``` 5. **Restart MCP Client** - Completely close and reopen your MCP client --- ### **Problem: Wrong Number of Tools** **Expected vs Actual:** - Essential mode: 20 tools - Standard mode: 32 tools - Advanced mode: 42 tools - Full mode: 60 tools **If you have 0 tools:** - WordPress credentials not set **If you have fewer tools than expected:** - Check `MCP_MODE` setting - Verify feature toggles in environment **Solutions:** 1. **Check Current Configuration** ``` What configuration mode is the MCP running in? ``` 2. **Verify Environment Variables** ``` Get the current configuration and show enabled features ``` 3. **Switch Modes** ```env MCP_MODE=full # Change this and restart ``` --- ## 🎨 **Elementor Issues** ### **Problem: Elementor Data Not Appearing on Frontend** **Symptoms:** - Page shows empty/blank - Layout doesn't render - Changes not visible **Solutions:** 1. **Verify Page Status** ``` Check if the page is published or draft ``` 2. **Clear Elementor Cache** ``` Clear the Elementor cache for this page ``` 3. **Check Template** - Ensure page template is set to "Elementor Canvas" or "Elementor Full Width" - Use `update_page` to set template 4. **Edit in Elementor First** - Open page in Elementor editor - Click "Update/Publish" to regenerate CSS - This forces Elementor to recognize the data 5. **Verify Elementor Metadata** ``` Get the page and check if _elementor_edit_mode is set to 'builder' ``` --- ### **Problem: Invalid Elementor Structure** **Symptoms:** - Elements not displaying correctly - Elementor editor shows errors - Layout broken **Solutions:** 1. **Validate Structure** - Every section needs at least one column - Every column can have multiple widgets - Element IDs must be unique 2. **Use Builder Tools** ``` Instead of manually creating structure, use: - create_section - create_column - create_heading/text/button ``` 3. **Extract and Review Structure** ``` Show me the structure of this page to see what might be wrong ``` 4. **Restore from Backup** ``` If page was working before, restore from last backup ``` --- ### **Problem: Widgets Not Displaying** **Symptoms:** - Some widgets missing - Widgets show as empty **Solutions:** 1. **Check Widget Type** - Use supported widget types: - heading, text-editor, button, image, divider, spacer 2. **Verify Widget Settings** - Each widget needs appropriate settings - Example: heading needs `title`, button needs `text` and `link` 3. **Check Elementor Version** - Some widgets require specific Elementor versions - Update Elementor if needed --- ## 📁 **File Operation Issues** ### **Problem: Export/Import Failures** **Symptoms:** - File operations fail - Permission denied errors - Files not found **Solutions:** 1. **Check Directory Permissions** ```bash # Ensure directories are writable chmod 755 ./data/exports chmod 755 ./data/backups ``` 2. **Verify Paths** - Use absolute paths - Check directory exists 3. **Check Disk Space** ```bash df -h # Check available disk space ``` 4. **Use Correct File Format** - Exports are JSON files - Must be valid JSON for import --- ### **Problem: Backup Restore Fails** **Symptoms:** - Restore operation errors - Data not restored correctly **Solutions:** 1. **Verify Backup ID** ``` List all backups to find the correct ID ``` 2. **Check Backup File** ``` Get file info for the backup to ensure it's valid ``` 3. **Validate Backup Data** ``` Validate the backup file before restoring ``` --- ## ⚡ **Performance Issues** ### **Problem: Slow Operations** **Symptoms:** - Operations taking too long - Timeouts - Slow responses **Solutions:** 1. **Use Chunked Operations** ``` For large pages, get Elementor data in chunks of 10 elements ``` 2. **Reduce Batch Size** - Instead of processing 100 pages, do 10 at a time 3. **Switch to Lower Mode** ```env MCP_MODE=standard # Instead of full ``` 4. **Clear Caches** ``` Clear all Elementor caches ``` 5. **Optimize WordPress** - Use caching plugin - Optimize database - Upgrade hosting if needed --- ### **Problem: Memory Issues** **Symptoms:** - Out of memory errors - Node.js heap errors **Solutions:** 1. **Increase Node Memory** ```json { "mcpServers": { "ultimate-elementor-mcp": { "command": "node", "args": [ "--max-old-space-size=4096", "/path/to/dist/index.js" ] } } } ``` 2. **Use Chunked Data Retrieval** ``` Get data in smaller chunks instead of all at once ``` 3. **Clean Up Old Backups** ``` Delete backups older than 30 days ``` --- ## 🔒 **Permission Issues** ### **Problem: Cannot Create/Update Content** **Symptoms:** - "You don't have permission" errors - 403 Forbidden errors **Solutions:** 1. **Check User Role** - Must be Administrator or Editor - Contributor has limited permissions 2. **Verify Capabilities** - WordPress user needs: - `edit_posts` - `edit_pages` - `upload_files` - `edit_others_posts` (for team sites) 3. **Check Post Status** - Some statuses require specific permissions: - `publish` requires `publish_posts` - `private` requires `publish_posts` 4. **Elementor Permissions** - Check Elementor → Tools → Role Manager - Ensure role can access Elementor --- ### **Problem: Cannot Upload Media** **Symptoms:** - Upload fails - Permission denied for media **Solutions:** 1. **Check `upload_files` Capability** - User must have media upload permissions 2. **Verify File Size Limits** - Check WordPress max upload size - PHP `upload_max_filesize` setting - PHP `post_max_size` setting 3. **File Type Restrictions** - WordPress only allows certain file types - Check `wp_config.php` for `ALLOW_UNFILTERED_UPLOADS` --- ## 🔍 **Diagnostic Commands** ### **Check MCP Status** ``` Run a health check and show me: 1. Current configuration mode 2. Total enabled features 3. WordPress connection status 4. Error statistics ``` ### **Debug Connection** ``` Test the WordPress connection and show detailed results ``` ### **Verify Configuration** ``` Validate the current configuration and show any issues ``` ### **Check Elementor** ``` Get the Elementor data for page ID 123 and verify it's valid ``` --- ## 📊 **Common Error Messages** ### **"WordPress environment variables not found"** **Cause**: Missing WordPress credentials in configuration **Fix**: ```env WORDPRESS_BASE_URL=https://your-site.com WORDPRESS_USERNAME=your-username WORDPRESS_APPLICATION_PASSWORD=xxxxxxxxxxxxxxxxxxxx ``` --- ### **"Request failed with status code 401"** **Cause**: Authentication failed **Fix**: 1. Verify Application Password (no spaces!) 2. Check username is correct 3. Regenerate Application Password if needed --- ### **"Request failed with status code 404"** **Cause**: Resource not found **Fix**: 1. Verify the ID/slug is correct 2. Check content type (post vs page) 3. Ensure content exists --- ### **"No route was found matching the URL"** **Cause**: Invalid WordPress REST API endpoint **Fix**: 1. Verify WordPress REST API is enabled 2. Check WordPress version (5.6+ recommended) 3. Ensure custom permalink structure is set --- ### **"Content, title, and excerpt are empty"** **Cause**: Creating content without required fields **Fix**: ``` When creating posts/pages, always include at least a title ``` --- ### **"Cannot read properties of undefined"** **Cause**: Missing data or configuration **Fix**: 1. Check all required parameters are provided 2. Verify the element/content exists 3. Use diagnostic tools to inspect data --- ## 🆘 **Still Having Issues?** ### **1. Enable Debug Mode** ```env DEBUG_MODE=true LOG_LEVEL=DEBUG ``` This provides detailed logs of all operations. ### **2. Check Logs** Look for error messages in: - MCP client console - Terminal where MCP server is running - WordPress debug log (if enabled) ### **3. Gather Information** Before asking for help, collect: - WordPress version - Elementor version - Node.js version (`node --version`) - MCP mode and configuration - Full error messages - Steps to reproduce ### **4. Ask for Help** - **GitHub Issues**: [Create an issue](https://github.com/mbrown1837/Ultimate-Elementor-MCP/issues) - **Discussions**: [Join discussion](https://github.com/mbrown1837/Ultimate-Elementor-MCP/discussions) Include: - System information - Configuration (remove sensitive data!) - Error messages - What you were trying to do - What actually happened --- ## 💡 **Prevention Tips** 1. **Always Backup** before major changes 2. **Test on Staging** site first 3. **Use Draft Status** initially 4. **Start Simple** and add complexity gradually 5. **Monitor Logs** for warnings 6. **Keep Updated** to latest versions 7. **Regular Maintenance** - clean up old files --- **🔧 Most issues have simple solutions. Don't hesitate to ask for help!** 🚀