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, open Linkilo → Settings → Diagnostics, click Copy report under Copy system report for support, and paste it into your email to 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.

If you see a red notice saying another Linkilo plugin is active, deactivate and delete the older copy. Only one copy of Linkilo can run.

I only see "Complete Install" under Linkilo

Normal before your first scan. Click Complete Install, work through the Initial Setup wizard and click Perform Scan at the end. The full menu (Link Priorities, Add URLs, Focus Keyword, reports) appears once the scan has run.

My license won't activate

Check in order:

1. No extra spaces in the key. Copy from your linkilo.co account carefully.
2. License not expired — check the renewal date.
3. License has activations left — multi-site licenses have a cap. Free a slot under Manage Sites on linkilo.co.
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.

Activate from the license screen (click Linkilo in the sidebar before activation) or from Linkilo → Settings → Licensing. If none of these help, 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 click Build Queue (or Open Scan Settings) to open Processing Settings and lower it. The recommended starting point is 50%.
2. Posts too short. Linkilo needs at least 200–300 words per post to find good matches.
3. Post Types filter wrong. In Processing Settings, make sure your blog post type is ticked; also check Settings → General → Scan these post types.
4. Exclude Recently Processed Posts is on. Turn it off in Processing Settings if you want already-analyzed posts included.
5. Content hasn't been processed. Go to Settings → AI Settings, step 3 Process your content, and check the processing statistics. If posts are pending, click Start AI Content Processing.
6. Provider key problem or monthly cap reached. In AI Settings, click Test Core Provider. Check the AI Usage Meter against your caps in step 2; when a cap is reached, AI work pauses until next month. Also confirm your provider account has credit.

Suggestions are weird / off-topic

• Reject the weak ones. Click Reject with Feedback. Linkilo never repeats the same source, target and anchor, and after three different anchors are rejected for the same pair of posts, the pair is blocked.
• Raise the Minimum Confidence Level in Processing Settings.
• Add a Linking rule in Settings → AI Settings, step 4 Linking rules, and tick Follow AI Rules from Settings in Processing Settings.
• Set post profiles in the editor (the Linkilo AI Profile box).
• Add stop words under Settings → Content & Ignored Words for phrases that keep turning into anchors.

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:

• The Autopilot bar on the AI Suggestions page shows an old Last run for hours or days
• A warning at the top of Linkilo pages: Linkilo — Background tasks may not be running.

Fixes:

1. Click "Run pending background tasks now" in the warning. 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.

Manual runs from Build Queue don't depend on WP-Cron — they run through your browser while the page is open.

"Unknown error" on the Suggestions page

Usually a PHP notice corrupting the response.

1. Tick Debug Mode at the top of the AI Suggestions page and run the scan again to see the log.
2. Check Settings → Diagnostics — the Last recorded error panel often shows the real cause.
3. Disable other plugins one at a time to find a conflict.
4. Email support the error message and the copied system report.

Provider bills growing fast

• Check the caps. Settings → AI Settings, step 2: Request cap and Estimated cost cap ($) default to 1,000 requests and $25 a month on new installs. Lower them if you like; 0 means no cap.
• Watch the AI Usage Meter at the top of AI Settings for estimated provider spend by model.
• Reduce automation — in step 5, turn off Weekly site sweep or lower Max posts per sweep.
• Exclude post types you don't need scanned and lower Max Posts to Process in Processing Settings.
• Set a hard limit in your provider's own account dashboard as a second guard-rail.

Per-Post Suggestions (Metabox)

The metabox doesn't appear in the post editor

The Linkilo AI Suggestions box is added to every public post type. If it's missing, check Screen Options at the top-right of the post editor — make sure Linkilo AI Suggestions is ticked. The separate inbound box only appears when Settings → General → Show links-into-this-post panel is on.

"Get AI Suggestions" hangs

The metabox sends a request to your AI provider. If it hangs:

1. Check your provider key with Test Core Provider in AI Settings, and that the account has credit.
2. Check your server's outbound HTTP. Many shared hosts block outbound connections to api.openai.com. Contact your host to whitelist it.
3. Wait longer for very long posts (30+ seconds).
4. Use Get Legacy Suggestions meanwhile — it needs no provider at all.

Display / Styling

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

1. Confirm Use my theme's link style in Settings → Internal Links is OFF (when it's on, your theme decides).
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 → Behavior → Position — try a different side, or increase Offset.

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

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 Summary page are blank

1. If a chart says Loading chart data… for a long time or suggests running a scan, click Refresh Dashboard, then Perform Scan if it stays empty. After upgrading from 2.9 you must run Perform Scan once; the charts are built on first load.
2. If the empty state lists row counts (links table, Summary snapshot, per-post counts) that are all zero, the scan hasn't recorded anything yet — run Perform Scan.
3. Hard-refresh your browser and purge any caching plugin — cached old JavaScript is a common cause.
4. Open the browser console (F12) and look for errors; send them to support if they persist.

Link Growth Over Time starts recording on the day you install or upgrade to 3.0 — a single point is normal at first.

Click Analytics shows no clicks despite traffic

1. Confirm tracking is enabled (Settings → Click Analytics → Record link clicks).
2. Confirm you're counting the right types under Which clicks to count (Clicks to your own pages / Clicks that leave your site).
3. Check a live blog post's source HTML — search for linkilo_url_click_tracker. If missing, a caching plugin or theme is stripping it.
4. Remember that clicks by site administrators are never recorded.
5. Wait — with Bundle clicks together on, clicks are written every few minutes.

Background Tasks / Cron

Tasks were running, now they've stopped

WP-Cron got broken somehow.

1. Open any Linkilo page and look for the Linkilo — Background tasks may not be running warning.
2. Click Run pending background tasks now if shown.
3. Check Settings → Diagnostics → Background activity to see what is queued.

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.

My host says Linkilo is using too many resources

Go to Settings → Diagnostics and click Turn on Safe Mode. All background processing pauses while your reports and settings keep working. Turn it off again once your host confirms things are back to normal.

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 link records are stale. Go to Linkilo → Summary and click Perform Scan to rebuild them. Orphan Pages, Link Priorities and Fix Link Health all read from these records.

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:

• Google Search Console isn't connected (the report is built from Search Console queries)
• You have no cannibalizations (good!)
• Search Console data hasn't synced yet — click Sync GSC Data Now in Settings → Google Search Console

Link Priorities or Fix Link Health is empty

Both read the links table. Run Perform Scan from the Summary page first. On Fix Link Health, click Refresh Queue after the scan finishes.

Connected sites (cross-site linking)

The other site never sees my connection request

On the other site, make sure Enable cross-site linking is on and saved in Linkilo → Settings → Advanced → Connected sites, then look under Requests from other sites in that card. Requests stay open for 2 days. If the row on your site says Request expired, add the site again.

An error appears when I connect or import

The Connected sites card says what went wrong, for example The other site's Linkilo licence is not active, Cross-site linking is off on the other site or The other site no longer recognises this connection (the row then shows Needs reconnecting). Each message is explained in How to connect other external sites you own.

Both sites must be reachable on the public internet. Linkilo cannot connect to localhost or private network addresses, and sites behind a proxy or CDN that changes their IP address are not supported yet.

Performance

My WordPress admin feels slow

• Reports page by page — the Add URLs list and report pages are paged; keep the per-page count low.
• Click Analytics history too long — in Settings → Click Analytics, set Keep click history for to 90 or 180 days.
• Re-scan posts every time they are saved (Settings → Advanced) is on — turn it off for high-edit sites.
• Still slow? Use Performance Safe Mode in Settings → Diagnostics while you investigate.

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. Copy the system report. Settings → Diagnostics → Copy system report for support → Copy report. It bundles everything we need.
2. Email support with the report pasted in + 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.

Last reviewed for Linkilo 3.0.0 (October 2026).