Troubleshooting

This guide covers common issues you might encounter with WyvernPress and how to resolve them.

Plugin Issues

WyvernPress Panel Not Appearing

Symptoms: The WyvernPress sidebar panel doesn’t show in the block editor.

Solutions:

1. Verify plugin is activated

   # Via WP-CLI
   wp plugin list | grep wyvernpress

   If inactive, activate it in Plugins → Installed Plugins.

2. Check for JavaScript errors

   • Open browser DevTools (F12)
   • Go to Console tab
   • Look for red errors mentioning WyvernPress

3. Clear browser cache

   • Press Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac)
   • Select “Cached images and files”
   • Clear and reload the editor

4. Deactivate conflicting plugins Common conflicts:

   • Other Gutenberg enhancement plugins
   • JavaScript optimization plugins
   • CSS minification plugins

Plugin Won’t Activate

Symptoms: Error message when activating WyvernPress.

Common Causes & Solutions:

Error	Solution
”PHP version not supported”	Upgrade to PHP 8.1+
“WordPress version too old”	Update to WordPress 6.4+
“Fatal error: Class not found”	Run composer install or re-upload plugin
”Memory limit exceeded”	Increase PHP memory limit to 256M+

Check PHP version:

wp eval "echo PHP_VERSION;"

---

Styling Issues

Styles Not Appearing on Frontend

Symptoms: CSS looks correct in editor but not on published page.

Solutions:

1. Clear all caches

   • WordPress object cache
   • Page caching plugin (WP Super Cache, W3 Total Cache, etc.)
   • CDN cache (Cloudflare, etc.)
   • Browser cache

2. Verify post is published

   • Drafts don’t show custom styles to visitors
   • Check post status in the editor

3. Check for CSS conflicts

   • Open DevTools → Elements tab
   • Select the styled element
   • Look for overriding styles (crossed out CSS)
   • Theme CSS may have !important declarations

4. Inspect the CSS output

   • View page source (Ctrl+U)
   • Search for “wyvernpress”
   • Verify CSS is present in <style> tags

Styles Disappear After Saving

Symptoms: Applied styles vanish when reopening the post.

Solutions:

1. Verify you clicked “Apply Styles”

   • Generate CSS → Preview → Apply Styles (must click this!)
   • Then save/publish the post

2. Check block attributes

   • DevTools → Console
   • Type: wp.data.select('core/block-editor').getSelectedBlock()
   • Look for wyvernpressCSS attribute

3. Database permissions

   • WordPress might not be saving post meta
   • Check for database errors in debug log

CSS Overriding Theme Styles

Symptoms: WyvernPress CSS conflicts with theme.

Solutions:

1. Increase specificity manually

   • Edit the generated CSS
   • Add more specific selectors

2. Use !important sparingly

   • Edit CSS: color: #0073aa !important;
   • Only use when necessary

3. Contact theme developer

   • Request they reduce CSS specificity
   • Or ask for WyvernPress compatibility

---

AI Generation Issues

”AI Generation Failed” Error

Symptoms: Error when generating complex styles.

Solutions:

1. Verify API key

   • Go to WyvernPress → Settings
   • Re-enter your OpenRouter API key
   • Test with “Test Connection” button

2. Check API credits

   • Log into OpenRouter
   • Verify you have available credits
   • Top up if necessary

3. Try a different model

   • Settings → AI Model
   • Switch from GPT-4 to Claude 3 Haiku (more reliable)

4. Simplify your prompt

   • Break complex requests into smaller pieces
   • Use Pattern Library terms when possible

Slow AI Responses

Symptoms: AI takes 10+ seconds to respond.

Solutions:

1. Use faster models

   • Claude 3 Haiku (fastest)
   • Claude 3.5 Sonnet (fast + quality)
   • Avoid GPT-4 for simple requests

2. Check your connection

   • AI requests go through OpenRouter
   • Test your internet speed
   • Try from a different network

3. Simplify prompts

   • Shorter prompts = faster responses
   • Use Pattern Library for simple styles

AI Generates Wrong CSS

Symptoms: CSS doesn’t match your description.

Solutions:

1. Be more specific

   • Bad: “Make it look nice”
   • Good: “Blue (#0073aa) background, white text, 16px padding, 8px border-radius”

2. Use CSS terminology

   • “padding” instead of “space inside”
   • “margin” instead of “space outside”
   • “border-radius” instead of “round the corners”

3. Try a different model

   • Claude models are best for CSS
   • GPT-4 is more creative but sometimes incorrect

4. Edit manually

   • Click “Edit CSS”
   • Adjust the generated code
   • Apply the corrected version

---

Pattern Library Issues

Patterns Not Matching

Symptoms: Pattern Library returns low confidence, falls back to AI.

Solutions:

1. Use exact pattern terms

   • See Pattern Library Reference
   • Use “blue” not “azure” or “cerulean”
   • Use “shadow” not “elevation”

2. Simplify your request

   • One concept at a time
   • “Add shadow” then “Make it blue”

3. Check for typos

   • “shadw” won’t match “shadow”
   • Patterns are normalized but typos still fail

Custom Patterns Not Working

Symptoms: Added custom patterns via filter but they don’t match.

Solutions:

1. Verify filter syntax

   add_filter( 'wyvernpress_patterns', function( $patterns ) {
       $patterns['my pattern'] = array(
           'background-color' => '#ff0000',
       );
       return $patterns; // Must return!
   } );

2. Clear pattern cache

   • WyvernPress → Settings → Clear Cache
   • Or: wp cache flush

3. Check filter priority

   • Default priority is 10
   • Use higher priority if overriding existing patterns

---

Performance Issues

Slow Editor Loading

Symptoms: Block editor takes long to load with WyvernPress.

Solutions:

1. Enable Redis object caching

   • Install Redis Object Cache plugin
   • Configure Redis connection
   • Reduces database queries significantly

2. Increase PHP memory

   • define('WP_MEMORY_LIMIT', '256M'); in wp-config.php

3. Disable unused features

   • WyvernPress → Settings → Disable features you don’t use

High Server Load

Symptoms: Server slows down when using WyvernPress.

Solutions:

1. Use Pattern Library

   • 60% of requests can use patterns
   • Zero external API calls
   • Much faster than AI

2. Enable caching

   • Install a page caching plugin
   • Enable object caching (Redis/Memcached)
   • Use a CDN

3. Batch operations

   • Style one element, copy to others
   • Don’t regenerate identical styles

---

Browser & Compatibility Issues

Safari/Firefox Specific Issues

Symptoms: Works in Chrome but not other browsers.

Solutions:

1. Clear browser data

   • Each browser has separate cache
   • Clear specifically for your site

2. Check for browser extensions

   • Ad blockers can interfere
   • Disable extensions temporarily

3. Update browser

   • Use latest browser version
   • Safari requires macOS updates

Mobile Editor Issues

Symptoms: WyvernPress panel hard to use on mobile.

Solutions:

1. Use tablet or desktop

   • Block editor is not optimized for phones
   • WyvernPress follows WordPress patterns

2. Request desktop site

   • In mobile browser, request desktop version
   • Provides more screen space

---

Debug Mode

Enable Debug Logging

For advanced troubleshooting, enable WordPress debug mode:

// In wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Then check wp-content/debug.log for WyvernPress-related errors.

WyvernPress Debug Info

Get plugin status:

# Via WP-CLI
wp eval "var_dump(\WyvernPress\Core\Plugin::get_instance()->get_status());"

Check API Connectivity

Test OpenRouter connection:

# Via WP-CLI
wp eval "
\$integration = \WyvernPress\Freemius\Freemius_Integration::get_instance();
var_dump(\$integration->test_api_connection());
"

---

Getting Help

Before Contacting Support

Gather this information:

• WordPress version (wp core version)
• PHP version (wp eval "echo PHP_VERSION;")
• WyvernPress version (Plugins page)
• Browser and version
• Error messages (exact text or screenshot)
• Debug log entries

Support Channels

• Documentation: You’re here!
• GitHub Issues: Report bugs
• WordPress.org Forums: Community support

Common Info to Include

WordPress: 6.x.x
PHP: 8.x.x
WyvernPress: 1.x.x
Browser: Chrome 120
Error: "Exact error message here"
Steps to reproduce:
1. Step one
2. Step two
3. Error occurs

---

Quick Fixes Checklist

Try these steps for most issues:

• Clear browser cache
• Clear WordPress cache
• Deactivate and reactivate WyvernPress
• Verify API key (if using AI)
• Check for plugin conflicts (deactivate other plugins)
• Update WordPress to latest version
• Update WyvernPress to latest version
• Check debug.log for errors

---

Next Steps

• Basic Usage Guide → - Learn the basics
• AI Styling → - Configure AI features
• Pattern Library → - Use instant patterns