# Troubleshooting

> **TL;DR:** Common issues include links not redirecting (check permalink settings and flush rewrite rules), clicks not tracking (check caching plugins and bot filters), and health scans not running (verify WordPress cron is active). Most problems resolve by flushing permalinks or clearing your cache.

Quick solutions to common problems with Link Manager Pro.

## Quick Fixes

Try these first — they resolve most issues:

1. **Clear all caches** — browser, WordPress, and server/CDN
2. **Flush permalinks** — go to **Settings → Permalinks → Save Changes**
3. **Deactivate other plugins** — reactivate one at a time to find conflicts
4. **Update WordPress and the plugin** — make sure you run the latest versions

## Links Not Working

### Link shows 404

- Check the link exists in **Pretty Links**
- Check the **Active From** date — the link may be scheduled for the future
- Check the **Expires At** date — the link may have expired
- Flush permalinks: **WordPress Dashboard → Settings → Permalinks → Save Changes**
- Check the link prefix has not changed (**Settings → General → Link Structure Prefix**)
- Clear all caches

### Link redirects to wrong URL

- Edit the link and verify the **Destination URL**
- Check **conditional routing rules** — a rule may be redirecting to an alternate URL
- Check for conflicts with other redirect plugins
- Clear all caches including CDN

### Password-protected link not working

- Verify **Password Protection** is set in the link editor
- Try in an incognito/private browser window
- Check that cookies are enabled — password auth uses a cookie

## Tracking Issues

### Clicks not recording

- Verify **Click Tracking** is enabled in **Settings → Tracking**
- Check if your IP is in the **Blocked IP Addresses** list
- Check if **Bot Detection** is filtering your user agent
- Wait a few minutes — clicks are logged after the redirect completes, so there is a slight delay
- Check the **Click Data Retention** setting — old data may have been purged

### Click count seems too high

- Likely bot traffic — enable **Bot Detection** in **Settings → Tracking**
- Add suspicious user agent patterns to **Custom Patterns** under Bot Detection
- Add suspicious IPs to **Blocked IP Addresses**
- Review analytics for patterns (regular intervals, same country)

### Internal clicks not tracking

- Verify **Internal Link Click Tracking** is enabled in **Settings → Tracking**
- Check the **Content Selector** setting matches your theme's content area
- Verify the page is not an admin, AJAX, or REST context
- Check the browser console for JavaScript errors
- The tracker requires same-origin: the source page must be on the same domain
- Rate limit: 30 requests per minute per IP

## Auto-Linking Issues

### Auto-links not appearing

- Verify **Auto-Linking** is enabled in **Settings → Auto-Linking**
- Check the specific link or affiliate has **Enable Auto-Linking** turned on
- Verify keywords are set and spelled correctly
- Check the post type is included in the **Auto-Linking Post Types** setting
- Check **Max Per Page** limit is not set too low
- Auto-linking skips admin, AJAX, cron, and REST contexts
- Cache may be stale — auto-link cache refreshes every 3600 seconds

### Too many auto-links or wrong keywords matched

- Reduce **Max Per Keyword** and **Max Per Page** in settings
- Enable **Case Sensitive Matching**
- Use longer, more specific keyword phrases
- Adjust **Auto-Link Priority** (lower number = higher priority)
- Enable **Exclude Headings** to skip h1–h6 tags
- Maximum 200 keywords supported — excess keywords are dropped by priority

## Health Monitoring Issues

### False positives in health scan

- Some servers block automated HEAD requests (the scan uses a 3-second timeout)
- Geographic blocking may cause false results
- Temporary server issues resolve on the next scan
- Test the URL manually in your browser
- Mark the link as **Ignored** if it works correctly

### Health scan not running

- Check cron is working — install the WP Crontrol plugin to verify
- Check **Automated Link Health Scans** in **Settings → General** is set to daily or weekly
- The scan processes 5 posts per cron run — large sites need multiple runs
- Check the server is not blocking `wp-cron.php`

## Disclosure Issues

### Disclosure notice not appearing

- Verify disclosure is enabled in **Settings → Disclosure**
- Check the post type is in the **Disclosure Post Types** list
- The notice only appears on pages that contain masked links or links with `nofollow` or `sponsored` REL attributes
- Check **Disclosure Text** is not empty
- Check the page source for the disclosure HTML — it may be hidden by theme CSS

## Coverage Score Issues

### Coverage score is low

- Check for orphaned posts (no inbound internal links) — these carry the heaviest penalty
- Check for broken links — each broken link has a high penalty weight
- Check for weak posts (few inbound or outbound links)
- Run a full link audit scan from **Link Audit**
- Add internal links to orphaned posts using the link suggestion feature

## Campaign Issues

### Campaign not showing in list

- Campaigns appear when links have `utm_campaign` values set
- Virtual campaigns auto-detect from link UTM data
- Managed campaigns appear in the list immediately after creation
- Check the spelling of the `utm_campaign` value matches across links

## Conditional Rules Issues

### Rule not triggering

- Check the rule's active toggle is enabled
- Check the **Start** / **End** date range includes the current date
- Check condition values: country codes must be 2-letter ISO codes, dates must be valid
- Check **Match Mode**: "All conditions" requires every condition to match, "Any condition" requires at least one
- Check **Priority**: lower number = evaluated first, first matching rule wins
- Check the rule's **Target URL** is valid

## Import/Export Issues

### Import fails

- Import expects **JSON** format (not CSV)
- Ensure the file was exported from Link Manager Pro's backup feature
- Check file encoding is UTF-8
- For large files, the import processes in batches — wait for completion
- Check PHP `memory_limit` and `upload_max_filesize`

### Export has no data

- Verify you selected items to include in the export
- Check you have administrator access
- Check the plugin's backup directory is writable

## Migration Issues

### Migration from Pretty Links or BetterLinks fails

- Verify the source plugin is still installed (its database tables must exist)
- Check the conflict strategy: **skip** skips existing slugs, **overwrite** replaces them
- Migration processes in batches — wait for all batches to complete
- Check PHP `memory_limit` for large datasets

## Common Error Messages

| Error | Solution |
|-------|----------|
| Link already exists | Choose a different slug |
| Invalid destination URL | URL must start with `http://` or `https://` |
| Permission denied | Log in as Administrator or a role with `manage_link_manager_pro` capability |
| Domain already in use | Each affiliate must have a unique domain |
| Rate limit exceeded | Internal click tracker allows max 30 requests/minute per IP |

## Database Reset

If the plugin is in a broken state and you need to start fresh, you can reset all plugin tables by visiting:

```
yoursite.com/lmp/migrate/fresh
```

> **Warning:** This drops and recreates all plugin database tables. All links, clicks, affiliates, categories, rules, and settings are permanently deleted. This cannot be undone.

To use the database reset:

1. Log in to your WordPress site as an Administrator.
2. Navigate to `yoursite.com/lmp/migrate/fresh` in your browser.
3. Read the confirmation warning.
4. Click **Run Fresh Migration** to proceed.
5. Wait for the success page to appear.

During the reset, all plugin API calls return a temporary 503 error until the migration completes. Only one reset can run at a time. Non-administrators cannot access this page.

Use this only as a last resort when the plugin is not functioning correctly and other troubleshooting steps have not resolved the issue.

## Still Need Help?

1. Check the [FAQ](https://docs.linkmanagerpro.com/faq)
2. Visit [https://linkmanagerpro.com/support](https://linkmanagerpro.com/support?utm_source=docs&utm_medium=referral&utm_campaign=troubleshooting)
3. When contacting support, include:
   - WordPress version
   - Plugin version (currently 1.1.0)
   - PHP version
   - Error messages or screenshots
   - Steps to reproduce the issue