Troubleshooting Guide

This section provides detailed diagnostic steps for the most common issues. Each entry includes symptoms, likely cause, and a step-by-step fix. If none of the solutions here resolve your problem, contact support at [email protected] with your WordPress version, SEO Forge version, PHP version, and screenshots of any error messages.

Tooltip Help Opens the Homepage Instead of the Article

Symptoms: Clicking the small ? help icon in SEO Forge admin opens the SEO Forge landing page or docs homepage instead of the specific article for that setting. Fix: Update SEO Forge to the current build. Admin help links now route to exact User Guide or Developer Guide section URLs. If a cached admin page still has the old link, hard-refresh the page once.

Forge Suite Deactivate on a Clone Affects Another Site

Symptoms: You cloned or restored a WordPress site, then clicked Forge Suite > Deactivate on the clone. Another site using the same license appeared to lose PRO or Connect state. Cause: Older builds trusted the Freemius install id stored in fs_accounts. A cloned database can carry the original site’s install id and URL, so even an install-scoped Freemius deactivation can target the original remote install. Fix: Update SEO Forge to the latest build. Forge Suite now compares the stored Freemius site URL with the current WordPress site_url() / home_url() before any remote deactivation. If the state belongs to another site, it skips the remote Freemius call and only clears local license state for the current WordPress install. Reconnect the clone through SEO Forge > License > Connect to Avakode when you want it to be licensed again.

Score Not Updating After Edits

Symptoms: You have edited the content or changed the focus keyword, but the SEO score in the editor or post list still shows the old value. Cause: Auto-analyze is disabled, the browser is showing a cached version, or the analysis engine did not fire on save. Fix:

Open the post in the editor
In the SEO Forge box, click the Re-analyze button to manually trigger a fresh analysis
Go to SEO Forge > Settings > General and confirm that Auto-analyze on save is enabled
If using a caching plugin, clear the page cache after making changes
Hard-refresh your browser with Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
If the problem persists, go to Plugins > Installed Plugins, deactivate SEO Forge, then reactivate it — this reinitializes the analysis hooks

Issues List Not Refreshing While I Type

Symptoms: The score circle ticks up as you type, but the Issues list under it (and the count badge on the SEO tab) is stuck on what was there when you opened the post. Cause: The live Issues refresh sends a small AJAX call to the server about 600 ms after you stop typing. If the call is blocked (an admin-area firewall plugin, an overzealous WAF rule, a misconfigured .htaccess, or a network blip) the existing list stays put rather than flicker to empty — that’s by design. So a stuck list almost always means the AJAX call is being blocked or erroring. Fix:

Open browser DevTools → Network panel, filter by admin-ajax.php, then type something in the focus keyword field. You should see a POST with action=seoforge_get_issues.
If the request is missing entirely → another script is hijacking input events. Disable browser extensions, then deactivate other admin-side plugins one at a time (start with form / autosave / “improve admin” plugins).
If the request returns 403 → either the WP nonce expired (reload the post-edit page) or your role lost edit_post capability mid-session.
If the request returns 400 / 500 → check wp-content/debug.log for the PHP error. Most common cause: a third-party plugin filtered the_content and threw on a draft post.
As a workaround until you find the cause, save the post — the server-side analysis runs on save and the list will update.

HowTo “step preview” Panel Says I Have 0 Steps But My Headings Are There

Symptoms: You picked HowTo as the schema type, your post has H2 or H3 headings for each step, but the live preview panel keeps saying “No HowTo steps detected” and the schema is silently skipped on the frontend. Cause: The step extractor intentionally drops headings that look like questions, because Google flags HowTo steps that aren’t imperative as invalid. A heading is treated as a question when:

It ends with ? (or the full-width ？), OR
It starts with one of: how, what, why, when, where, who, which, whose, whom

Fix:

Rephrase question headings into imperatives. “How do I prep ingredients?” → “Step 1: Prep ingredients.” “What temperature do I bake at?” → “Set the oven to 220°C.”
If the post is genuinely a Q&A page (not instructional), pick FAQ as the schema type — that’s what FAQ schema is for.
If you really want imperative-looking content to ship as HowTo even though it starts with “How”, switch to [seoforge_step] shortcodes (the shortcode parser doesn’t apply the question filter — it trusts you’ve curated the steps explicitly).

Schema Not Appearing in Google Rich Results

Symptoms: You have enabled schema markup but Google does not display rich results (star ratings, FAQ dropdowns, breadcrumbs) for your pages. Cause: Schema may not be enabled, Google may not have recrawled the page, or the schema type may not match the content. Fix:

Confirm schema is enabled at SEO Forge > Settings > General > Schema enabled
View your page source (right-click on the page > View Page Source) and search for application/ld+json — if you see a JSON block, the markup is being output correctly
Go to Google’s Rich Results Test at search.google.com/test/rich-results and enter your page URL
Review any errors or warnings Google reports and fix them
If the schema is valid but rich results do not appear, wait 2–4 weeks — Google must recrawl and reprocess your page
Remember that rich results are not guaranteed — Google decides whether to display them based on quality signals, domain authority, and the specific query
Check that you are using the correct schema type for your content (e.g., Article for blog posts, Product for product pages, LocalBusiness for business pages)

Sitemap Returning 404

Symptoms: Visiting yoursite.com/sitemap_index.xml returns a “Page Not Found” error page. Cause: WordPress URL rewrite rules are stale, another plugin is conflicting, or .htaccess is not writable. Fix:

Go to Settings > Permalinks in the main WordPress settings (not SEO Forge settings)
Without changing anything, click Save Changes — this forces WordPress to regenerate URL rewrite rules
Try loading your sitemap again at yoursite.com/sitemap_index.xml
If still showing 404, check if another plugin is generating a conflicting sitemap — look for other active SEO plugins or standalone sitemap plugins and deactivate them
Verify that your .htaccess file (in the WordPress root directory) is writable — the file permissions should be 644 or 666
If using Nginx instead of Apache, make sure the WordPress rewrite rules are properly configured in your Nginx config file — virtual URLs like the sitemap require a try_files $uri $uri/ /index.php?$args; directive
Check your hosting control panel for any security rules or WAF settings that might block XML file access

“Temporary connection issue with Google Analytics” / “Access to Google Analytics was lost” / “Google Analytics Admin API needs to be enabled”

Symptoms: On SEO Forge → Analytics & Traffic, the property picker or one of the report tiles shows a warning card instead of your data. Three possible messages:

“Google Analytics Admin API needs to be enabled” with Open Google Cloud Console + I enabled it — retry buttons (added v1.0.8) — Google reports the GA Admin API is disabled on the GCP project the plugin uses.
“Temporary connection issue with Google Analytics” with a Retry button — Google’s API returned an unclassified 5xx or network error.
“Access to Google Analytics was lost” with a Reconnect Google button — your OAuth token was revoked.

Fix:

For “API needs to be enabled” — click Open Google Cloud Console (a new tab opens straight to the enable page Google asked for), click Enable, wait ~1 minute for Google to propagate the change, then return to the plugin and click I enabled it — retry. The picker reloads without you having to refresh the whole admin page.
For “Temporary connection” — click Retry. If the failure repeats, wait 1–2 minutes (Google’s data API has brief outages) and retry once more.
For “Access lost” — click Reconnect Google. A new tab opens the consent screen; approve the scopes. The admin tab reloads automatically when the new token is saved.
If “No GA4 properties on this account” appears, the connected Google account has no Analytics 4 properties. Click Reconnect and pick a different Google account — or create a GA4 property in analytics.google.com first.

Why the API-enable page looks scary the first time: Google Cloud Console asks for a confirmation because enabling an API on a project signs you up for usage tracking on it. The Analytics Admin API has a generous free tier (well above what a single SEO Forge install can hit), so it’s safe to enable. SEO Forge only ever uses the read paths (list properties + run reports) — it never writes to your Analytics setup. Why you never see raw Google API text: As of 2026-04 SEO Forge intercepts any API error and shows a localised warning card. The raw response is logged to the browser console (console.warn('[SEO Forge GA4]', …)) for developers — check the DevTools console if a support agent asks for the exact error.

URL Inspection metabox shows “Search Console API needs to be enabled”

Symptoms: On a published post’s edit screen, the Google index status panel inside the SEO Forge metabox shows a friendly orange card titled “Google Search Console API needs to be enabled” with an “Open Google Cloud Console” button — no coverage / last-crawl pills. Cause (added 2026-04-27 — v1.0.9): Same pattern as the GA Admin API case above. After connecting Google Search Console, every actual API call (list verified sites, run search analytics, inspect URL) requires the Search Console API to be enabled at the GCP project level. If it isn’t, Google returns a 400 with the exact enable URL embedded in the message, and SEO Forge surfaces that as a one-click CTA. Fix: Click Open Google Cloud Console — a new tab opens straight to the enable page Google asked for. Click Enable, wait ~1 minute for Google to propagate the change, then return to the post and click Re-check in the metabox. The plugin then saves a verified GSC property automatically — but only if a verified property’s URL prefix matches your WordPress home URL. If no host match exists, the plugin asks you to pick a property explicitly in Settings → Integrations rather than guessing (see the next entry).

URL Inspection says “No GSC property matches” or “doesn’t cover this URL”

Symptoms: After clicking Check status, the panel shows one of:

“No GSC property matches this WordPress site’s URL. Open SEO Forge → Settings → Integrations and pick the right property.” — the WP host doesn’t match any of the verified properties on the connected Google account.
“The saved GSC property doesn’t cover this URL. Open SEO Forge → Settings → Integrations and pick the right property.” — a previously-saved property doesn’t cover this specific URL (Google replied with “User does not have sufficient permission for site …” or “URL is not part of this property”).

Cause (added 2026-04-27 evening — v1.0.9 follow-up): Earlier the auto-pick fallback would silently save the first verified property if no host match existed. That worked on most installs but on edge cases (the verified property has read-only delegated access, or its URL prefix doesn’t cover this post’s URL) Google rejects every subsequent inspect call with a 4xx — and the plugin would keep retrying until cron rate-limited it. The “sufficient permission for site ‘sc-domain:…'” alert spike on 2026-04-27 evening was exactly this loop. Fix: Update SEO Forge to v1.0.9 (the late-evening rev). The plugin now (a) stops blindly picking the first verified property — if no host-match exists you get an actionable error pointing at Settings; (b) self-heals when Google reports a permission/coverage mismatch — it deletes the saved property so the next attempt re-runs auto-pick instead of hammering Google with a known-bad value.

To resolve the error itself: open SEO Forge → Settings → Integrations, click Change GSC property, and pick the verified property whose URL prefix actually covers this WordPress install. After that, Check status in the metabox returns proper coverage data.

Site Audit “Show NN pages” button does nothing on click

Symptoms: You ran a Site Audit. The issue cards render with the right counts and a Show 188 pages button under each one, but clicking the button does nothing — no expand, no error, the button stays inert. Cause (fixed 2026-04-26 — v1.0.8): The server-side audit renderer generates DOM IDs by passing the issue title through WordPress’s sanitize_title(). For Cyrillic (and other non-ASCII) titles sanitize_title() percent-encodes the bytes, so the DOM ID looks like sf-audit-acc-%d0%be%d1%82%d1%81.... The accordion JS then ran jQuery('#' + ariaControls) to find the target panel — and jQuery’s selector engine throws a “Syntax error, unrecognized expression” when it sees % inside an ID. The exception silently killed the delegated click handler so the button registered the click but did nothing visible. Fix: Update SEO Forge to v1.0.8. The handler now uses native document.getElementById, which accepts any literal string ID (no CSS-selector parsing), so the lookup works for any audit issue title regardless of language.

Google Search Console Not Connecting

Symptoms: Clicking the Connect button in SEO Forge > Settings > Search Console fails, shows an error, or the authorization process does not complete. Cause: Browser popup blocker, expired authorization, network issue, or incorrect Google account. Fix:

Make sure you are logged into the correct Google account — the one that has access to your site’s Search Console property
Disable any popup blockers in your browser, as the authorization flow opens a new window
Clear your browser cookies for google.com and try the authorization again
Check that your site URL in WordPress (Settings > General > Site Address) exactly matches the property URL in Google Search Console (including http vs https and www vs non-www)
If you see a “redirect_uri_mismatch” error, your WordPress URL has changed since the plugin was installed — go to SEO Forge > Settings > Search Console, disconnect, and reconnect
Verify your internet connection — the authorization requires communication with Google’s servers
If using a security plugin (Wordfence, Sucuri, etc.), temporarily disable it to see if it is blocking the OAuth callback URL

Google Connected but the Admin Page Still Shows “Connect Google”

Symptoms: After completing the Google OAuth flow in the new tab, the browser returns to your admin and the Integrations page still offers Connect Google instead of showing the connected state. Cause (fixed 2026-04-24): The callback tab used window.opener.postMessage to nudge the admin tab to reload. Chrome 88+ and Safari 13+ can drop the window.opener reference during the Google cross-origin redirect chain even with rel="opener", so the message never arrived. Fix: Update SEO Forge to the latest version. The admin now uses three redundant completion paths — the original postMessage, a 2-second poll of admin-ajax?action=seoforge_gsc_status for up to three minutes after you click Connect, and a visibilitychange listener that re-checks status the moment the admin tab becomes visible. Any of the three triggers an automatic reload when the connection lands in the database.

If the page still does not reload after a minute, open a fresh admin tab on SEO Forge > Settings > Integrations — the connected state will be visible on page load regardless.

Credit Balance Looks Doubled After Site Audit

Symptoms: The credits chip in the plugin header shows a suspiciously large number after running Site Audit (for example 5,183 / 5,000 — remaining greater than total). Navigating to Content Brief appears to “fix” it. Cause (fixed 2026-04-24): A new-user (post-migration) code path in the Worker promoted base_credits from 0 to the tier limit on every /ai/process response, causing total = base + granted to suddenly include the monthly tier quota that the user should not have had. The credit chip rendered this inflated total. Fix: Update SEO Forge to the latest version. The Worker now applies the legacy-user check symmetrically on both the pre- and post-deduct credit reads, so base_credits stays at 0 for non-legacy users and total correctly reflects only the license bonus plus purchased add-on packs.

If you already see an inflated total, refresh the admin page once — the chip re-reads the corrected balance on next render.

Credits Chip Does Not Refresh After Site Audit

Symptoms: You run a Site Audit (10 credits), but the credits chip in the header keeps showing the pre-audit number until you do a full browser reload. Cause (fixed 2026-04-24): The admin-side ajaxSuccess hook that refreshes the chip matched only REST calls (/seoforge/v1/*). Site Audit runs through admin-ajax (?action=seoforge_run_audit), which is outside the REST namespace and therefore outside the refresh hook’s match list. Fix: Update SEO Forge to the latest version. The hook now covers both REST paths and a list of credited admin-ajax actions, so the chip re-fetches the fresh balance within a second of any credited action (Site Audit, Content Brief, Fix with AI, Local SEO generation, and the rest).

Google OAuth and URL Inspection permission hardening (2026-05-07)

The Google OAuth return path is now bound to the WordPress site that started the flow: the callback only redirects back to a same-origin /wp-admin/ URL for that site. URL Inspection also checks edit_post for the selected post before sending the request to Forge API, so users can only inspect URLs for posts they are allowed to edit.

Generate Brief Button Looks Clickable When Disabled

Symptoms: On AI Content Brief Generator, the Generate Brief button is greyed out when you have not yet typed a target keyword, but it still shows the full orange fill and a hover animation — it looks clickable. Cause (fixed 2026-04-24): The disabled attribute was set correctly, but the plugin’s CSS did not style the :disabled / [disabled] / [aria-disabled="true"] pseudo-states, so WordPress’s default disabled styling was overridden by our button skin. Fix: Update SEO Forge to the latest version. Disabled primary and secondary buttons now render desaturated grey with cursor: not-allowed and no hover lift, shimmer, or colour change — matching the logical disabled state with an unmistakable visual one.

Native Browser Confirm Pop-up for “This Action Costs X Credits”

Symptoms: When you click Generate Brief or another heavy AI action, the browser shows its native OS-level confirm dialog with the site domain in the title bar, instead of the plugin’s styled modal. Cause (fixed 2026-04-24): The shared credits widget that intercepts heavy-action clicks for confirmation was still calling window.confirm(). The earlier pretty-modal work replaced in-plugin confirms but never reached the shared widget. Fix: Update SEO Forge to the latest version. The widget now renders its own styled modal with a crystal icon, title, message, and gradient primary button — and it ships inside the shared widget so Lang Forge, Form Forge, and Field Forge get the same dialog.

View / Delete Buttons on Brief History Do Nothing

Symptoms: On AI Content Brief Generator, the Recent briefs list renders correctly but clicking View or Delete does nothing — or the network panel shows a 404 on /wp-json/seoforge/v1/brief/history/{id}. Cause (fixed 2026-04-24): Brief IDs are generated via substr(wp_generate_uuid4(), 0, 12), which keeps the first hyphen (for example 077719a9-a47). The REST route’s URL parameter regex only accepted [a-z0-9]+, so any ID with a hyphen never matched the route and WordPress returned a 404 at the router layer. Fix: Update SEO Forge to the latest version. The route regex was widened to [a-z0-9-]+. View and Delete now hit the handlers correctly; existing briefs in history become usable immediately, no data migration required.

“Brief Already Exists” Warning Stays After a Fresh Generation

Symptoms: Immediately after generating a new brief, the orange banner “A brief with this keyword already exists” appears, which is confusing — you just created it. Cause (fixed 2026-04-24): The duplicate-hint watcher compared the current keyword against the full history, which includes the brief you just generated. Correct logically, misleading in practice. Fix: Update SEO Forge to the latest version. After a successful generation the hint is suppressed for that keyword until you modify the input — so you only see “already exists” when you actually re-type an old keyword.

Fix with AI Applied Directly Without the Preview Drawer

Symptoms: On Site Audit, clicking Fix with AI on any issue applies the change immediately and removes the row, without opening the right-side review drawer where you could edit the suggestion first. Cause (first iteration fixed 2026-04-24, expanded 2026-04-26): v1.0.6 narrowed the drawer to title / description / focus-keyword and matched issues by English text only — which broke for Russian audit messages and for the per-issue “Fix all N with AI” button. v1.0.7 expansion: even after that, content-rewrite issues (thin content, duplicate titles, no internal links, missing H1, missing alt) continued to apply silently because the drawer had no preview path for the post-body rewrite endpoint. Fix: Update SEO Forge to the latest version. Fix buttons now carry an explicit data-issue-type code (language-neutral). v1.0.7 adds two new REST endpoints (/seoforge/v1/fix/preview and /seoforge/v1/fix/apply) and a new drawer “content” mode (large textarea, no character counter). v1.0.9 closes the last gap: bulk Fix on content types now opens the same N-accordion review drawer with “Apply All” that meta types already used (collapsed-by-default for items 2..N, internal scroll on long suggestions) — earlier the per-issue “Fix all N with AI” or sticky “Fix selected (N)” on content rewrites fell back to single-fix on the first item only.

Site Audit Disappears After You Fix a Single Issue

Symptoms: You ran Site Audit, clicked Fix with AI on one page, navigated to another tab and came back — the Site Audit page is empty and asks you to Run Audit again, even though you only fixed one of dozens of issues. Cause (fixed 2026-04-26): Every successful single fix, bulk fix, or drawer Apply called delete_option('seoforge_site_audit_result') to invalidate the cached snapshot. The intent was “show fresh state next time”, but the side-effect was deleting the entire audit just because one page got fixed. Fix: Update SEO Forge to the latest version. v1.0.7 surgically prunes the audit instead — only the fixed posts are removed from their issue groups; if a group becomes empty it’s dropped; the rest of the audit stays put across navigation. Severity counts are recomputed automatically. The whole audit is only rebuilt when you click Run Audit again, which is the only path that should ever reset it.

Brief Viewer Stays Open After You Delete That Brief

Symptoms: On AI Content Brief, you open a saved brief from Recent briefs, then delete it from the same Recent briefs row. The row disappears, but the expanded brief at the top of the page stays visible until you manually reload. Cause (fixed 2026-04-26): The delete handler refreshed the history list but never touched the expanded brief panel above it. The panel had no concept of “which brief am I currently showing” so it had no way to react to a delete event for that specific brief. Fix: Update SEO Forge to the latest version. The viewer now stores the brief id on its container element. When the delete success callback fires for that id, the viewer is hidden and emptied. If you delete a different brief while viewing one, the viewer stays put — only the matching deletion clears it.

Connect Google Card Stays on “Connect” After Successful OAuth (manual reload doesn’t help)

Symptoms: You completed Google OAuth in the new tab, the success page told you you’re connected, but the SEO Forge Settings → Integrations card still shows Connect Google. Even pressing F5 keeps showing the disconnected state. Cause (fixed 2026-04-26): Two separate problems compounded. (1) The connection state was cached in a 5-minute WordPress transient — if is_connected() cached “no” right before you clicked Connect, that “no” persisted across reloads for up to five minutes. (2) On the worker side, the OAuth callback didn’t wrap the token-save call in try/catch, so a silent D1 write failure could render a “Connected” success page while leaving the integration empty. Fix: Update SEO Forge to the latest version. The transient TTL drops from 5 minutes to 30 seconds, and the cache is busted automatically when the Connect button is rendered, so the page you bounce back to after OAuth always re-asks the worker. On the worker side, token persistence failures now surface a real error response and a structured log entry (google_oauth_save_tokens_failed) instead of a misleading success page.

Deleted SEO Title / Description Still Rendering After Save

Symptoms: You cleared the SEO Title or Meta Description in the SEO Forge metabox and pressed Update, but a hard refresh of the page still shows the old text in search-result previews or page meta. Cause (fixed 2026-04): Clearing the field used to save an empty-string value to wp_postmeta. WordPress stored that as a real row, and some downstream consumers (SERP preview, A/B variant lookup) could still read it as a truthy value — so the cascade to Taxonomy / Global template / WordPress fallback never kicked in. Fix: In 2026-04 the save path was changed — when you clear the field and save, the whole meta row is deleted. The cascade then resolves cleanly (Post-level override → Taxonomy → Global template → WP default). You will see the template-resolved title (e.g. %title% | %sitename%) or the raw post title as WP’s final fallback — not the ghost of the deleted value. If you still see old content: clear your server-side cache (W3 Total Cache / WP Super Cache / Cloudflare / LiteSpeed) — the deleted meta change cannot reach visitors while a stale HTML page is being served from cache.

Meta Tags Not Showing on the Page

Symptoms: When you view the page source, you do not see SEO Forge meta tags (og:title, description, etc.) in the HTML head section. Cause: Another plugin or theme is overriding the output, or the wp_head hook is not being called. Fix:

View your page source (right-click > View Page Source) and search for seo-forge or og:title to check if any tags are present
Confirm that another SEO plugin is not active — two SEO plugins will conflict on meta tag output
Check that your theme’s header.php file includes in the section — this is the hook SEO Forge uses to output tags
If using a page builder with a custom header template, make sure the wp_head() call is included in the custom template
Temporarily switch to a default WordPress theme (Twenty Twenty-Five) to see if the tags appear — if they do, your theme is the issue
Check if a caching plugin is serving a stale version without the tags — clear all caches

Duplicate Meta Tags (Theme or Plugin Conflict)

Symptoms: When viewing the page source, you see two sets of meta tags — for example, two tags or two sets of Open Graph tags. Cause: Your theme or another plugin is also outputting meta tags, creating duplicates. Fix:

View the page source and identify both sets of tags — note which one comes from SEO Forge and which comes from the theme or another plugin
If the duplicates come from Yoast, All in One SEO, SEOPress, or Rank Math, update SEO Forge first. Current builds suppress their common frontend description, robots, Open Graph, and Twitter output while SEO Forge is active. Yoast’s title presenter can remain active because it reads SEO Forge’s resolved document title, which keeps migration periods safer without leaving the page title blank on themes that rely on Yoast for the tag.
Deactivate the old SEO plugin after importing its data — only one SEO plugin should be active long-term
If the duplicates come from your theme:

– Check your theme’s settings for an option to disable built-in SEO features or meta tag output

– Look for a setting called “SEO,” “Meta Tags,” or “Social Sharing” in the theme customizer or options panel

– If no such option exists, contact the theme developer and ask how to disable their meta tag output

If the duplicates come from a social sharing plugin (like Social Warfare or Monarch), check its settings for an option to disable OG tag output
As a last resort, a developer can add a code snippet to your theme’s functions.php to remove the duplicate action from the wp_head hook

Redirects Not Working

Symptoms: You have set up a redirect in the Redirect Manager but visiting the old URL does not redirect to the new one. Cause: Cache interference, incorrect URL format, or redirect rules not flushing. Fix:

Go to SEO Forge > Redirects and verify the redirect entry is listed and the status is “Active”
Check that the source URL uses the correct format — it should be a relative path like /old-page/ without the domain name
Clear all caches: browser cache, page cache, CDN cache, and any server-side caching
Go to Settings > Permalinks and click Save Changes to refresh rewrite rules
Test the redirect in an incognito/private browser window to rule out browser caching
If using Nginx, check that your server is not caching redirects at the server level
Check if a .htaccess redirect rule or server-level redirect is overriding the plugin’s redirect — server-level rules execute before WordPress loads

404 Tracking Not Logging Visits

Symptoms: The 404 log in SEO Forge shows no entries even though you know 404 errors are occurring on your site. Cause: Caching plugin is intercepting 404s before they reach WordPress, or the feature is disabled. Fix:

Confirm that 404 tracking is enabled in SEO Forge > Settings (PRO feature)
Test by visiting a URL on your site that you know does not exist — like yoursite.com/this-page-does-not-exist-12345
Go back to the 404 log and check if the visit was recorded
If not recorded, check your caching plugin settings — some caching plugins intercept 404 responses and serve their own error page without triggering WordPress, which means the plugin never sees the request
In WP Rocket: go to Advanced Rules > Never Cache URL(s) and add a wildcard rule if needed
In LiteSpeed Cache: check the 404 caching setting and disable it
Check if your hosting provider has server-level 404 handling that bypasses WordPress entirely — this is common on managed hosting platforms

AI Features Not Responding

Symptoms: Clicking any AI button (Generate Title, AI Fix, Content Brief, etc.) does nothing, shows a spinning indicator that never completes, or shows a generic error message. Cause: Expired or missing PRO license, depleted AI credits, network issue, or API outage. Fix:

Confirm you have an active PRO license — AI features are not available in the free version
Check your AI credit balance at seoforge.dev — if it’s zero, buy a pay-as-you-go pack (packs never expire and go straight into your account pool)
Verify your internet connection — AI features require your WordPress site to communicate with the Forge API
Check if a firewall, security plugin, or hosting-level rule is blocking outgoing HTTP requests to api.seoforge.dev
Open your browser’s developer console (F12 > Console tab) and click the AI button again — look for error messages that might indicate what is failing
If you see a timeout error, your hosting provider may be limiting external API call duration — contact them about increasing the max_execution_time PHP setting
Check the Forge API status page at status.seoforge.dev to see if there is a known outage
Try deactivating and reactivating your PRO license under SEO Forge > Settings > License

Local SEO “Generate All Fields” Button Stuck on “Generating…”

Symptoms: On the Local SEO page you click Generate All Fields after filling in the business name, city, and type. The button changes to “Generating…” and never comes back. Page reload doesn’t help. Fix (v1.0.1+): Resolved in commit 16f3bec. If you’re on a newer release the button now fails with a visible error message within 90 seconds instead of hanging. If the issue still reproduces:

Make sure you’re on SEO Forge 1.0.1 or newer — this bug was fixed in SF-78.
Open the browser console (F12) and click Generate again — errors are printed there.
Check the Forge API status page — Local Schema generation hits the same AI endpoint as the rest of the plugin.

Auto-Link “Wiped Out the Rest of My SEO”

Symptoms: You ran Auto-Link on a post with a good SEO score (for example 81). The button added one or two internal links but your overall score dropped sharply (for example to 59). Your title, description, or section headings look different after the click. Cause and fix (v1.0.1+): The old Auto-Link button sent the full post body to the AI and saved a rewritten version. Even small rewrites changed word count, keyword density and heading structure — which dropped the score as a side effect.

Since SF-84 (commit 16f3bec) Auto-Link runs a local linker instead: it only wraps existing anchor phrases in tags and does not modify the rest of your content. Word count, headings, keywords and score stay byte-identical before and after Auto-Link. If you’re still seeing score changes after Auto-Link:

Make sure you’re on SEO Forge 1.0.1 or newer.
Check the revision history of the post — Auto-Link no longer saves a new content revision unless it actually inserted a link.

Broken Links Scanner Stuck or Not Completing

Symptoms: The broken links scan starts but never finishes, gets stuck at a certain percentage, or shows “Scanning…” indefinitely. Cause: PHP timeout limits, large number of pages, or server resource constraints. Fix:

Check how many posts and pages your site has — sites with thousands of pages will take longer to scan
If the scan is stuck, go to SEO Forge > Broken Links and click Cancel Scan, then start a new scan
SEO Forge scans links in batches using WordPress cron. Verify that WordPress cron is working correctly by installing the WP Crontrol plugin and checking for scheduled SEO Forge events
If your site uses an alternative cron setup (like a server-level cron job calling wp-cron.php), make sure it is running at least every 5 minutes
Increase PHP memory and execution time limits if you have access to php.ini:

– memory_limit = 256M

– max_execution_time = 300

On shared hosting, consider running the scan during off-peak hours when server resources are less constrained
If the scan repeatedly fails at the same percentage, there may be a specific URL causing a long timeout — check your server error logs for clues

OG Image Not Showing on Social Media

Symptoms: When sharing a page on Facebook, Twitter/X, or LinkedIn, the link preview does not show an image or shows the wrong image. Cause: Missing OG image tag, social platform caching an old version, or image does not meet size requirements. Fix:

View your page source and search for og:image — confirm the meta tag is present and the URL points to a valid image
Check that the image meets minimum size requirements: Facebook requires at least 1200×630 pixels, Twitter requires at least 800×418 pixels
Verify that the image URL is accessible publicly (not behind a login or firewall)
Clear the social platform’s cache:

– Facebook: Use the Sharing Debugger at developers.facebook.com/tools/debug/ — enter your URL and click “Scrape Again”

– Twitter/X: Use the Card Validator at cards-dev.twitter.com/validator

– LinkedIn: Use the Post Inspector at linkedin.com/post-inspector/

SEO Forge chooses the OG image in this order: per-post Social Media Image (SEO box → Social tab) → stored social image URL if the attachment ID is stale → featured image → WooCommerce placeholder on product pages → site default (Settings → Social → Default Social Image). Confirm at least one of these is set and meets the size requirements.
If you set a per-post Social Media Image and social still shows the old one, it’s almost certainly platform caching — re-scrape with the tools in step 4.
Check that the image file is not blocked by your robots.txt file.

Robots.txt Conflicts

Symptoms: Search engines are not crawling parts of your site, or your custom robots.txt rules are being overridden. Cause: Another plugin is generating a conflicting virtual robots.txt, or a physical robots.txt file exists in the root directory. Fix:

Visit yoursite.com/robots.txt in a browser and check what is being served
Check if a physical robots.txt file exists in your WordPress root directory — if it does, WordPress (and SEO Forge) cannot override it with a virtual one. Either edit the physical file directly or delete it to let SEO Forge manage it. If the file is a SEO Forge-managed file with an old sitemap host, update SEO Forge and reload settings; current builds repair that managed sitemap line to the current site URL.
If the robots.txt content does not match what you configured in SEO Forge, another plugin may be overriding it — temporarily deactivate other plugins one by one to identify the conflict
Go to SEO Forge > Settings > Robots.txt and review your rules
Make sure you have not accidentally added a Disallow: / rule, which blocks all crawling
After making changes, use Google Search Console’s URL Inspection tool to verify that Google can crawl your pages

Page Source Shows `noindex, nofollow` While SEO Forge Post Settings Are Indexable

Symptoms: The SEO Forge Advanced tab does not have Noindex/Nofollow enabled for a post, but the frontend source still shows . Cause: WordPress core’s Settings > Reading > Discourage search engines from indexing this site option is enabled. This global core setting has priority over per-post SEO plugin settings. Fix: If the site should be public, disable Discourage search engines in WordPress Reading settings. If the site is staging/private, leave it on; SEO Forge intentionally preserves the core noindex, nofollow directive.

Content Decay Not Detecting Declining Pages (PRO)

Symptoms: The Content Decay feature shows no declining pages even though you know traffic to certain pages has dropped. Cause: Google Search Console is not connected, insufficient data history, or the decay threshold has not been reached. Fix:

Confirm that Google Search Console is connected in SEO Forge > Settings > Search Console
Content Decay detection requires at least 30 days of Search Console data — if you just connected, wait for data to accumulate
Check the decay threshold in settings — the default is a 20% decline over 30 days. If your traffic drops are smaller than this, they will not be flagged
Go to SEO Forge > Content Decay and check the date range — make sure it covers the period where you suspect traffic dropped
Verify that the specific pages you are concerned about are indexed in Google — noindexed pages will not have Search Console data

SEO A/B Test Not Showing Results (PRO)

Symptoms: You have set up an A/B test but the results page shows no data or says “Insufficient data.” Cause: Not enough time has elapsed, low traffic pages, or Search Console data not syncing. Fix:

A/B tests need at least 14 days of data to produce meaningful results — check the test start date
The page being tested needs consistent search traffic — low-traffic pages take longer to reach statistical significance
Confirm Google Search Console is connected and syncing properly
Check that the test is in “Running” status — it may be paused or draft
Do not make any other SEO changes to the page being tested during the test period, as this introduces variables that invalidate results

—