# Troubleshooting FAQ

## Plugin / Activation Issues

### The plugin shows a white screen or fatal error on activation

**Cause:** PHP version below 5.3.2 or WordPress below 3.5.

**Fix:** Check server PHP version. The activation hook (`on_cp_activate`) calls `wp_die()` if requirements aren't met and deactivates the plugin.

```php
// Minimum requirements
PHP >= 5.3.2
WordPress >= 3.5
```

### Admin notice: "PharData extension is not available"

**Cause:** The `PharData` PHP extension is not loaded on the server. This extension is required to extract the MaxMind GeoLite2 database `.tar.gz` archive.

**Fix:**
1. Ask your host to enable the `phar` PHP extension
2. Or dismiss the notice if you are not using geolocation targeting

The notice can be dismissed via the `cp_dismiss_phardata_notice` AJAX action, or suppressed by setting the `cp_show_phardata_notice` option to `'no'`.

---

## Campaigns & Subscribers

### Subscriber count is not updating

**Possible causes:**
- The form submission AJAX nonce (`cp-submit-form-{style_id}`) is failing — often due to aggressive caching
- The `cp_add_subscriber` AJAX endpoint is blocked by a security plugin

**Fix:**
1. Exclude `wp-admin/admin-ajax.php` from your caching rules
2. Check browser console for AJAX errors on form submission
3. Enable debug mode (see below) and check for PHP errors

### Campaign not showing in the style editor

**Cause:** The campaign may be trashed or the `smile_lists` option may be corrupted.

**Fix:**
1. Go to **WP Admin > Campaigns** and check if the campaign is visible
2. If missing, recreate the campaign
3. Check `wp_options` for the `smile_lists` key and verify its content

---

## Geolocation

### Geolocation targeting is not working

**Possible causes:**
1. MaxMind database file has not been downloaded
2. The license key is invalid
3. Server does not have internet access to download the database
4. `PharData` extension is missing

**Fix:**
1. Go to **WP Admin > Convert Plus > Settings** and verify the MaxMind license key
2. Click "Download Database" and check for errors
3. Verify the file exists at `wp-content/uploads/convertplus_uploads/`
4. Ensure `PharData` is enabled on your server

---

## Styling & Display Issues

### Popups are not displaying on the front end

**Check:**
1. The style is enabled (green status in the module list)
2. The module is enabled in **WP Admin > Convert Plus > Modules**
3. Targeting rules are not excluding the current page/user
4. There are no JavaScript console errors preventing the front-end JS from loading

### CSS is not loading / styles look broken

**If async CSS loading is enabled:**
Async CSS loading (`convert_plug_settings['cp-load-syn'] = '1'`) uses JavaScript to load stylesheets. Browsers with JS disabled or aggressive CSP policies may block this.

**Fix:** Disable async CSS loading in **Convert Plus > Settings**.

### Conflict with Imagify plugin

Convert Plus automatically dequeues conflicting Imagify scripts via `cp_dequeue_script_imagify()` (runs on `wp_print_scripts` at priority 999). If you still see conflicts, check if the dequeue is firing.

---

## Debug Mode

### Enabling Debug Mode

1. Go to **WP Admin > Convert Plus > Settings > Debug** tab
2. Enable "Dev Mode" — loads unminified JS and CSS assets
3. Enable "Display Debug Info" — outputs debug information in the admin footer

Or set the option directly:

```php
update_option( 'convert_plug_debug', array(
    'cp-dev-mode'           => '1',
    'cp-display-debug-info' => '1',
));
```

### Checking the Debug Panel

The debug panel is accessible at:
```
wp-admin/admin.php?page=convert-plus&view=debug&author=true
```

---

## Import / Export

### Import fails: "Could not extract the archive"

**Cause:** `PharData` extension is not available.

**Fix:** Enable the `phar` PHP extension on your server.

### Import fails: style already exists

Convert Plus checks for duplicate style names on import. Rename the style before re-importing.

---

## Analytics

### Analytics data is showing zero impressions

**Cause:** The `smile_update_impressions` AJAX call may be blocked.

**Check:**
- Front-end JS is loading (no 404 or JS errors)
- `wp-admin/admin-ajax.php` is reachable from the front end
- The style ID is correctly set in the front-end rendered HTML

### Resetting analytics

From **WP Admin > Campaigns > [Campaign] > Analytics**, use the "Reset Analytics" button.

Or via AJAX: `cp_reset_analytics_action` with the `style_id` parameter.

---

## Access / Permissions

### Non-admin users cannot see the Convert Plus menu

**Cause:** The user's role is not in the allowed roles list.

**Fix:** Go to **Convert Plus > Settings** and add the role to "Access Roles". The plugin grants/revokes the `access_cp` capability on `wp_loaded`.

---

## Getting Help

- Knowledge Base: **WP Admin > Convert Plus > Knowledge Base**
- Support: https://www.convertplug.com/plus/support/
- GitHub Issues: https://github.com/brainstormforce/convertplug/issues

## Related Pages

- [Environment Configuration](Environment-Configuration)
- [Geolocation Targeting](Geolocation-Targeting)
- [Build Tooling](Build-Tooling)
- [Admin Panels](Admin-Panels)