Troubleshooting

Stuck? Most problems have quick fixes. Search this page for your symptom (Ctrl-F / Cmd-F) or scroll through.

If you can't find your issue here, generate a support export (see Advanced) and email support.

Installation and License

I uploaded the plugin but don't see Linkilo in my admin menu

The plugin probably didn't activate. Go to Plugins → Installed Plugins. Find Linkilo. Click Activate.

If Linkilo isn't in the list at all, the upload didn't finish — try uploading again.

My license won't activate

Check in order:

1. No extra spaces in the key. Copy from your purchase email carefully.
2. License not expired — check the renewal date.
3. License has activations left — multi-site licenses have a cap.
4. Your site is reachable from our server. License validation pings linkilo.co. Firewalls or proxies can block this. Have your host whitelist *.linkilo.co.

If none of these, email support with your license key.

"Connection to license server failed"

Your server can't reach linkilo.co. Usually a firewall or proxy issue. Whitelist *.linkilo.co and try again.

AI Suggestions

My scan returned zero suggestions

Multiple possible causes:

1. Minimum Confidence Level too high. On the AI Suggestions page → Processing Settings, lower it to 0.3.
2. Posts too short. Linkilo needs at least 200–300 words per post to find good matches.
3. Post Types filter wrong. Make sure your blog post type is checked.
4. OpenAI key has no credit. Log in to platform.openai.com → Usage. Top up if balance is $0.
5. Engine threshold too high in Settings. Settings → AI Settings → Suggestion Quality Threshold — set to 0.4 or lower.

Suggestions are weird / off-topic

• Reject the weak ones. Linkilo learns. After 3 rejections of a source→target pair, it's hard-blocked.
• Tighten the threshold. Raise Suggestion Quality Threshold to 0.7+.
• Use Custom Rules to block specific patterns (Settings → AI Settings → AI Rules).
• Set post profiles in the editor (Linkilo profile metabox).

Autopilot isn't running

Background jobs in WordPress depend on WP-Cron. Many managed hosts (Kinsta, WP Engine, etc.) have WP-Cron disabled or unreliable.

Symptoms:

• AI Dashboard shows "Recent processing sessions: none" for hours/days
• Yellow notice at the top of Linkilo pages saying tasks are stalled

Fixes:

1. Click "Run pending tasks now" in the yellow notice. Fires every Linkilo background job manually.
2. Set up a real cron. Have your host configure a system-level cron that hits wp-cron.php every 5 minutes.
3. Install Action Scheduler (free plugin) — gives WordPress a more reliable scheduling system.

"Unknown error" on the Suggestions page

Usually a PHP notice corrupting the AJAX response.

1. Turn on Debug mode (Settings → Advanced → Show PHP errors). Refresh. See the real error.
2. Disable other plugins one at a time to find a conflict.
3. Email support the error message.

OpenAI bills growing fast

• Set a hard monthly cap in your OpenAI account → Usage limits.
• Reduce scan frequency — turn off weekly sweep or lower max posts per sweep.
• Exclude post types you don't need scanned.
• Lower max suggestions per run.

Per-Post Suggestions (Metabox)

The metabox doesn't appear in the post editor

Settings → General → Suggestion metabox → Show metabox in the post editor must be on.

If still missing, check Screen Options at the top-right of the post editor — make sure Linkilo Suggestions is checked.

"Get Suggestions" hangs

The metabox makes an AJAX call to OpenAI. If it hangs:

1. Check OpenAI key has credit.
2. Check your server's outbound HTTP. Many shared hosts block outbound connections to platform.openai.com. Contact your host to whitelist.
3. Wait longer for very long posts (30+ seconds).

Display / Styling

Internal links don't change color even though I set a color

1. Confirm the master toggle in Settings → Internal Link Styling is ON.
2. Save Settings (often missed).
3. Clear your caching plugin.
4. Hard-refresh browser (Ctrl+Shift+R / Cmd+Shift+R).
5. Your theme may override — try the Custom CSS class workaround.

Link Preview hover card looks broken / cut off

Themes with overflow: hidden on the article container clip the card.

Quick fix: Settings → Link Preview → Behaviour → Position — try a different side.

If persistent, contact theme support to remove overflow: hidden from post content wrappers.

A "Thank you for using Linkilo" message appears in the middle of a page

Old bug from a previous Linkilo release that left a debug message in the rendered HTML. Should be gone in current versions. If you still see it: update Linkilo to the latest version, clear every cache layer (server, CDN, caching plugin, browser), and hard-refresh.

Toggles look like plain checkboxes

Plain checkboxes mean the toggle CSS didn't load. Hard-refresh browser, purge caching plugin, purge server-level caching.

Charts and Analytics

Charts on the dashboard are blank

Most common cause: cached old JavaScript.

1. Hard-refresh browser.
2. Purge caching plugin.
3. Open browser dev console (F12). Look for errors like TypeError: Chart.getChart is not a function. That means an old Chart.js is cached somewhere. Clear all caches.

Click Analytics shows no clicks despite traffic

1. Confirm tracking is enabled (Settings → Click Analytics → Record link clicks).
2. Confirm you're tracking the right types (Internal / External).
3. Check a live blog post's source HTML — search for linkilo_click_tracker. If missing, a caching plugin or theme is stripping it.
4. Wait — clicks are batched and written every few minutes.

Background Tasks / Cron

Tasks were running, now they've stopped

WP-Cron got broken somehow.

1. Check Linkilo → Dashboard for the yellow stalled-tasks notice.
2. Click Run pending tasks now if shown.

If that fixes it but tasks stop again, contact your host.

How do I make sure tasks run reliably?

Two approaches:

1. System cron — have your host trigger wp-cron.php every 5 minutes via real cron.
2. Action Scheduler — install the free Action Scheduler plugin (bundled with WooCommerce).

Either replaces default WP-Cron with something more reliable.

Reports

Orphan Pages shows my Contact / Privacy / About pages

Normal — nothing links to them from content. Add their URLs to Settings → Content & Ignored Words → Hide from orphan report.

A post is in Orphan Pages but I know it has links to it

Linkilo's index is stale. Linkilo → URL Records → Re-sync rebuilds the link index from scratch.

Anchor Report shows a weird anchor I don't remember adding

It's in your content somewhere — you just don't remember. Click the count to see every post using that anchor. Open one and Ctrl-F the anchor text to find it.

Keyword Cannibalization is empty

Either:

• GSC isn't connected
• You have no cannibalizations (good!)
• GSC data hasn't synced yet — click Sync in Settings → GSC

Multi-site / Cross-site

My other site doesn't appear in linked sites

Both sites need the same access code AND public HTTPS reachability AND active licenses.

"Failed to fetch URL list" on linked site

The two sites can't talk to each other. Causes:

• Behind a firewall or staging environment
• Mixed HTTP/HTTPS
• Localhost or not publicly reachable

Both sites need to be publicly accessible over HTTPS.

Performance

My WordPress admin feels slow

• AI Dashboard heavy stats — load other pages once you're done with it.
• URL Records too long — filter or paginate.
• Click Analytics history too long — reduce retention to 90 days.
• Re-index on save is on — turn it off for high-edit sites.

My public site feels slow

• Disable Link Preview temporarily to check.
• Disable Click Analytics temporarily to check.
• Otherwise, check if the slowdown is unrelated (server, theme, other plugins).

Anything else

1. Generate a support export. Settings → Advanced → Generate support export. Bundles everything we need.
2. Email support with the zip + a short description.
3. Include: what you were trying to do, what happened, any error message, browser + OS.

Most issues are resolved within 24 hours.