Skip to content
metacraft

Troubleshooting

Start with the developer log (CP → Logs → Developer). MetaCraft logs every problem it works around there, once per day per message, and never shows errors to visitors. If the head tag fails completely, the page still gets a plain <title> with the site name.

The SEO tab doesn't show on the publish form

  • The channel must be enabled and have Show the MetaCraft SEO tab ticked (Settings → Channels → Edit).
  • Custom publish layouts: MetaCraft adds its tab to existing layouts when you save the channel settings. If someone removed it from a layout, save the channel's MetaCraft settings again, or drag the MetaCraft SEO tab back in the layout editor.
  • The member's role needs permission to edit entries in that channel. The tab follows normal entry permissions.

The canonical URL is wrong

Find which source won: the publish tab badge next to Canonical URL (Custom / Mapped / Auto), or the entry's chips in Content SEO.

Symptom Likely cause
Wrong domain or index.php in the URL Settings → General → Base URL (the Canonical example line shows the result). Blank uses EE's base URL; set it explicitly if EE's includes index.php or an internal hostname.
Slash at the end comes and goes Trailing slashes set to Keep as is on a Structure site. Use Add (Settings → Advanced).
Points to another page The entry has a canonical override (tab) or a mapped canonical field. Clear it, or fix the mapped field's value.
Channel entry has no canonical, or the listing page's URL The channel has no URL pattern (Sitemap screen → Sources), or the template passes the wrong entry_id.
Page 2 canonicalizes to page 1 A canonical="…" parameter or an entry override is set. Both are used exactly as given, without the /P20 segment.
No canonical at all canonical="none" in the template, or the override isn't a valid URL. Check the developer log.

/sitemap.xml returns 404

What the 404 looks like tells you which part is missing:

The 404 is… Cause Fix
Plain text, just Not found MetaCraft answered, but the sitemap is switched off Sitemap screen → turn Enabled on
Your site's normal "page not found" page The request reached ExpressionEngine, but no template is routed to sitemap.xml, so MetaCraft never ran Create the sitemap template and its sitemap.xml route (setup), and turn on Settings → Template Settings → Enable template routes
A bare server page (e.g. nginx) The web server answers .xml itself and never asks ExpressionEngine See Hosting notes in XML sitemaps, or use static mode

/sitemap-2.xml returning 404 on a small site is expected: there's only one file.

In template mode MetaCraft never writes a sitemap.xml file to the server. The sitemap is built when /sitemap.xml is requested and cached inside MetaCraft, so no file appearing is normal. Only static mode writes files.

The browser shows an XML error for /sitemap.xml

Messages such as error on line 1 at column 1: Start tag expected, '<' not found mean the file isn't valid XML. MetaCraft's sitemap starts with <?xml and has no <changefreq>, <priority> or comments, so if you see those, the file isn't MetaCraft's. It's usually an old hand-made sitemap.xml left in the web root. Web servers send a real file before ExpressionEngine sees the request, so while that file exists, MetaCraft's sitemap is never reached and new pages never appear.

  1. Check what's being served. curl -s https://your-site/sitemap.xml | head -c 200 shows the first characters, and curl -sI shows the headers. A Last-Modified date from before MetaCraft was installed means a static file.
  2. Remove or rename the old file in the web root. Keep a copy if you want one.
  3. Set up the sitemap template (setup). If you use static mode instead, Regenerate now refuses while the old file is there, because MetaCraft never overwrites a file it didn't write.
  4. Purge the CDN or proxy cache. Headers such as x-cache: HIT and a large age mean a cached copy is still being served. Add any query string to skip the cache while you check: https://your-site/sitemap.xml?check=1.
  5. Resubmit the sitemap in Google Search Console, so it fetches the fixed version.

The sitemap lists pages that return 404

The sitemap lists every entry that's public and indexable. A page whose template sends a 404 (for example a Structure parent with no content of its own, or a page that isn't finished) is still listed. Check every URL with:

curl -s https://your-site/sitemap.xml | grep -o '<loc>[^<]*' | sed 's/<loc>//' | xargs -I{} curl -s -o /dev/null -w '%{http_code} {}\n' {} | grep -v '^200'

For each page it reports:

  • Not ready for anyone yet: set the entry's status to Closed. It leaves the site and the sitemap; set it back to Open when it's ready.
  • Visitors may see it, search engines shouldn't: SEO tab → Search indexing → Noindex. It's left out of the sitemap too.
  • Only a folder in the Structure tree (its child pages are real): SEO tab → XML sitemap → Exclude, and leave it open so its children keep working. Don't close a parent like this.
  • It should be a real page: fix its template so it renders.

The sitemap is out of date

  • It rebuilds on the next request after a change, not during the save. Load /sitemap.xml once, or click Regenerate now.
  • Static mode only changes when cron (or Rebuild static files when entries are saved) runs. Check the cron job and its PHP binary: php system/ee/eecli.php metacraft:sitemap --dry-run.
  • Status Error on the Sitemaps screen: the previous sitemap is still being served. The message and the developer log say why, e.g. a sitemap.xml that MetaCraft didn't write is in the way, or the folder isn't writable.
  • An entry is missing: check its status (public statuses), dates, robots (noindex is excluded), its Sitemap setting on the tab, and whether its canonical points elsewhere. Channel entries also need a URL pattern with Include in sitemap and Has detail pages on.

Tags appear twice in the page source

The Overview's list of templates that may output duplicate tags shows the templates and where each extra tag comes from (the template itself, its layout, an embed or a partial). Remove the old <title>, description, canonical, og: tags, {exp:seo_lite} or hand-written <script type="application/ld+json"> from that file.

If the panel is clean but you still see duplicates, another add-on is injecting tags after the template renders. Check add-ons that use template_post_parse.

There's no robots meta tag

That's expected for pages that can be indexed. MetaCraft leaves out <meta name="robots" content="index, follow"> because search engines index and follow pages without a robots tag, so the tag would add nothing. The page is still indexable: Google Search Console's URL Inspection confirms it.

The tag appears when a page is restricted (noindex or nofollow, from the entry, its channel, Settings → General or a template's robots= parameter) or has extra directives such as max-image-preview:large. If a page you expect to be indexable has a noindex tag, open its SEO editor: Search indexing under Search engine directives has a badge and a note saying where the value comes from. A template's robots= parameter isn't shown there, so check the template too.

A mapped field isn't used

  • Mapped values only apply in enabled channels, and only when the entry has no override for that field (an override beats a mapping).
  • Settings → Channels: the table shows a broken mapping in amber, and the channel's drawer keeps Missing field (#N) selected with a warning, for mappings whose field was deleted, moved out of the channel's field group, or changed to a type that can't be mapped.
  • Supported fieldtypes: Text input, Textarea, Rich Text (title / description / OG text), File (image), Text input or URL (canonical). Structured data also uses Date, URL and Grid fields (opening hours, questions and answers). Fluid, Bloqs and relationship fields can't be mapped.
  • A mapped canonical that isn't a full http(s) URL or a path starting with / is skipped. The canonical falls back to the entry's own URL.
  • The publish tab preview shows the mapped value as last saved. Save the entry to see a changed field reflected.
  • A mapped image needs a file that still exists in the file manager.

An entry's Event (or other type) isn't in the JSON-LD

Open the entry's editor and look at the preview's Structured data tab.

  • The type chip says WebPage and there's an amber note: a required property is empty or not mapped. Fill it in on the entry, or map it in Settings → Channels → the channel's Structured data. The Content SEO filter Schema incomplete lists every entry like this.
  • "needs a … column" in the channel drawer: the Grid doesn't have the columns MetaCraft looks for. Name (or label) them day, opens, closes for hours, or question, answer for FAQs.
  • Rows listed as skipped: MetaCraft couldn't read a day or time. Use day names or ranges (Mon–Fri) and times like 8:00 AM or 08:00.
  • A Product outputs as WebPage: its price is empty or has no currency. Use $25, 25.00 USD or EUR 19,90.
  • Medical details missing on a MedicalBusiness: schema.org doesn't define them for that type; choose MedicalClinic, Physician or Dentist.
  • Nothing at all: JSON-LD is off in Settings → Structured data, the channel's type is None, or the page uses schema="none".

Google decides whether to show a rich result; valid markup makes a page eligible, not guaranteed.

The Overview numbers look stale

Results are cached for about an hour, but any entry or setting change clears them. Re-check now forces a fresh audit. The counts cover published, live entries in enabled channels plus Structure pages, not drafts or closed entries.

MetaCraft screens look unstyled or half-old after an upgrade

MetaCraft's stylesheet and scripts are loaded with a version tag that changes whenever the files change, so browsers normally fetch the new ones straight away.

  • Hard-reload the page (⌘⇧R / Ctrl+F5) to rule out the browser.
  • A proxy or CDN in front of the control panel may ignore the query string. Purge admin.php?…C=css&M=third_party&package=metacraft… (and the javascript equivalent), or exclude the control panel from caching.
  • Check that the add-on was updated (Add-Ons shows an update button until it is). The files and the database must be on the same version.

A MetaCraft link logs me out or says I'm not allowed

EE keeps the control panel session in the URL (&S=…) on this kind of setup. A bookmarked or pasted CP link without a valid session sends you to the login page, and a few screens then can't send you back to where you were. Open MetaCraft from the sidebar and use the links inside it.

Old 1.0 links (settings_general, channels, channel/12, sitemaps, entries, import_seo_lite) redirect to the new screens once you're logged in.

If a page says Settings are limited to MetaCraft admins, your role isn't listed under Settings → Advanced → Who can change settings. Ask a Super Admin.

A page can't be read

The editor's capture line (above the preview) says why. Test the fix with Settings › AI › Page capture › Test capture.

Message Likely cause and fix
Page content available after publishing The entry is closed, future-dated or expired. Only public pages are read.
This entry has no URL The channel has no URL pattern (Sitemap screen → Sources), and the entry isn't a Structure page.
The page redirected (301/302) Usually the trailing-slash policy doesn't match the site's own URLs (Settings › Advanced), or the page forces a different host or https. Redirects aren't followed.
The page returned an error (404, 403, 500…) The URL MetaCraft built doesn't render on the site, or a security layer refuses the server's own requests. Open the entry's page in a browser to compare.
Couldn't reach the page / Couldn't read the page The server can't fetch its own public URL: basic auth on staging, a CDN or firewall blocking it, or DNS that doesn't resolve inside the server. Set a Capture URL (an internal address for the same site) and, if needed, basic auth.
401 Unauthorized on Test capture Basic auth username or password is wrong. A blank password field keeps the saved one.
Page too large to read Over 5 MB of HTML. Usually a page embedding large inline data.
The page was empty It returned 200 with no content, or only navigation and scripts. Check the template has a <main> or body content.

Pages also aren't re-read on their own until the capture command runs: add php system/ee/eecli.php metacraft:capture to cron (Reading pages).

AI suggestions don't appear, or fail

  • No Suggest buttons: AI is off, or no key is saved (Settings › AI). They also need permission to edit the entry, and the page to have been read (the capture line says so).
  • No bulk job on Content SEO: only MetaCraft admins see it, only with AI on, and only on the Missing description and Schema incomplete views.
  • "Anthropic rejected the API key": the key was revoked, mistyped or belongs to a disabled workspace. Replace it in Settings › AI and use Test key. With a config.php key, fix it there.
  • "Rate limit or quota reached": the Anthropic account is over its rate or spend limit. Wait a minute, or raise the limit in the Anthropic Console. Bulk jobs can be resumed.
  • "Anthropic isn't responding": a problem on Anthropic's side; nothing was charged. Try again later.
  • "Couldn't get a suggestion": the developer log has a line starting MetaCraft: AI suggestion for entry N failed with the HTTP status and error type.
  • The same suggestion comes back: the page hasn't changed since it was suggested, so nothing was sent. Suggest again (sends a request) asks anew.

"MetaCraft is not licensed on this domain"

ExpressionEngine reports that this site has no valid MetaCraft licence, or that it has expired. Nothing is disabled: the head tag, sitemaps, editing and every screen keep working. The notice shows only on MetaCraft's own screens, never to visitors or on the publish form.

For the first 7 days it counts down, then the wording firms up. To clear it, add or renew the licence in Add-ons (the add-on's licence key field) and load any control panel page. ExpressionEngine refreshes its licence check from the browser, so the notice can take one page load to disappear. Local development hosts (.ddev.site, .test, .local, localhost) never show it.