# Troubleshooting

## Common Issues

### Connection Issues

#### "Connection failed" status

**Symptoms**: The settings page shows "Connection failed" even after entering an API key.

**Solutions**:

1. **Verify API key**: Copy the key again from [Phynite Analytics settings](https://app.phyniteanalytics.com/settings/wordpress)

2. **Check for whitespace**: Ensure no extra spaces before/after the API key

3. **Test connectivity**: Your server must be able to reach `api.phyniteanalytics.com`
   ```bash
   # Test from server (if SSH access available)
   curl -I https://api.phyniteanalytics.com/health
   ```

4. **Check firewall rules**: Some hosts block outgoing connections. Contact your host if needed.

5. **SSL certificate issues**: Ensure your server's CA certificates are up to date

#### Sync starts but shows 0 posts

**Symptoms**: Bulk sync completes instantly with "0 posts synced"

**Solutions**:

1. Ensure you have published posts (not just drafts)
2. Check that post types are supported (posts and pages by default)
3. Verify the API key has proper permissions

---

### Sync Issues

#### Posts not syncing automatically

**Symptoms**: New or updated posts aren't appearing in Phynite Analytics

**Solutions**:

1. **Check WP-Cron**: The plugin relies on WordPress cron
   ```php
   // Add to wp-config.php to verify cron is running
   define( 'WP_DEBUG', true );
   define( 'WP_DEBUG_LOG', true );
   ```

2. **Verify cron is not disabled**:
   ```php
   // This should NOT be in wp-config.php
   define( 'DISABLE_WP_CRON', true );
   ```

3. **Check queue status**: Visit Settings → Phynite Analytics and check "Pending syncs"

4. **Manual cron trigger**: Install [WP Crontrol](https://wordpress.org/plugins/wp-crontrol/) to manually run cron jobs

#### Sync seems stuck

**Symptoms**: Progress bar doesn't move, or sync never completes

**Solutions**:

1. **Cancel and restart**: Click "Cancel" then "Sync All Content" again

2. **Check PHP timeout**: Long-running syncs may hit PHP limits
   ```php
   // In wp-config.php
   set_time_limit( 300 );
   ```

3. **Check memory limit**: Ensure adequate PHP memory
   ```php
   // In wp-config.php
   define( 'WP_MEMORY_LIMIT', '256M' );
   ```

4. **Clear the queue**: Use this snippet in a custom plugin or functions.php temporarily:
   ```php
   delete_option( 'phynite_sync_queue' );
   delete_option( 'phynite_sync_state' );
   wp_clear_scheduled_hook( 'phynite_process_sync_batch' );
   ```

#### High number of failed syncs

**Symptoms**: Retry queue keeps growing

**Solutions**:

1. **Check API status**: Visit [Phynite Status](https://status.phyniteanalytics.com)

2. **Review server logs**: Look for timeout or connection errors

3. **Enable debug mode**:
   ```php
   // In wp-config.php
   define( 'PHYNITE_DEBUG', true );
   ```

4. **Check rate limits**: If you're making too many requests, syncs will fail

---

### Plugin Conflicts

#### SEO data not being extracted

**Symptoms**: SEO fields are empty even though Yoast/RankMath/AIOSEO is installed

**Solutions**:

1. **Check plugin is active**: Ensure the SEO plugin is activated

2. **Verify detection**: Check "Detected Plugins" section in settings

3. **Check for custom fields**: The plugin looks for standard meta keys:
   - Yoast: `_yoast_wpseo_*`
   - RankMath: `rank_math_*`
   - AIOSEO: `aioseo_posts` table

4. **Multiple SEO plugins**: If multiple are installed, only the first detected is used

#### Recipe data not being extracted

**Symptoms**: Recipe fields are empty even though a recipe plugin is installed

**Solutions**:

1. **Verify supported plugin**: Only WPRM, Tasty Recipes, and Mediavine Create are supported

2. **Check recipe association**: Ensure recipes are properly linked to posts

3. **Database tables**: WPRM and Create use custom tables - verify they exist

---

### Performance Issues

#### Site becomes slow during sync

**Symptoms**: Admin or frontend is slow when bulk sync is running

**Solutions**:

1. **Reduce batch size**:
   ```php
   add_filter( 'phynite_batch_size', function() {
       return 10; // Smaller batches
   });
   ```

2. **Increase batch delay**: Edit the cron schedule interval

3. **Run during low traffic**: Start bulk syncs during off-peak hours

4. **Use WP-CLI**: For very large sites, consider CLI-based sync

#### High memory usage

**Symptoms**: PHP memory errors during sync

**Solutions**:

1. **Increase PHP memory**:
   ```php
   define( 'WP_MEMORY_LIMIT', '512M' );
   ```

2. **Reduce links extracted**:
   ```php
   add_filter( 'phynite_max_links_per_post', function() {
       return 50; // Fewer links
   });
   ```

---

### Debug Mode

Enable debug logging to diagnose issues:

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

Logs are stored in:
1. `phynite_debug_log` option (viewable via database or option inspector)
2. `wp-content/debug.log` (if WP_DEBUG_LOG is enabled)

---

## Getting Help

### Before Contacting Support

Please gather this information:

1. WordPress version
2. PHP version
3. Plugin version
4. Server/hosting provider
5. Other active plugins (especially SEO/cache plugins)
6. Error messages (from debug log if available)
7. Steps to reproduce the issue

### Support Channels

1. **GitHub Issues**: [Report bugs](https://github.com/phynite/phynite-analytics-wordpress/issues)
2. **Help Center**: [Phynite Help](https://help.phyniteanalytics.com)
3. **Email**: support@phyniteanalytics.com

---

## Uninstalling

To completely remove the plugin and all its data:

1. Go to **Plugins** in WordPress admin
2. Deactivate "Phynite Analytics for WordPress"
3. Click "Delete" to remove the plugin

This will:
- Remove all plugin options
- Clear all scheduled cron jobs
- Delete any transients created by the plugin
- Remove post meta created by the plugin