Troubleshooting

Lumtera doesn't start: "needs the PHP DOM extension"

Lumtera reads HTML with PHP's DOM extension. If your server doesn't have it, Lumtera shows "Lumtera needs the PHP DOM extension, which is not enabled on this server." and does nothing else. Ask your host to enable php-xml (DOM). It's switched on by almost every host.

The Accessibility sidebar doesn't appear in the editor

• Look for the Lumtera icon in the editor's top toolbar, or open the Options menu (⋮) and choose Accessibility checker.
• Check the content type is ticked under Settings → Content to check.

"This post is too large to check live"

Posts over 512 KB of content, or 5,000 blocks, aren't checked while you type. They're still checked when you save. Developers can raise the limit with lumtera_max_check_bytes.

"Too many checks in a short time"

Each user can run 120 live checks a minute. Wait a moment. Developers can change the limit with lumtera_check_rate_limit.

"Check all content" stopped

The message "The check stopped because of an error." usually means a single post failed to render. For example, a shortcode from a deactivated plugin may have caused a PHP error.

• Click Try again.
• Look in your PHP error log for the cause.
• If it keeps stopping, run wp lumtera scan --all in WP-CLI. Errors are shown on screen, which makes the cause easier to find.

A post shows "Not checked"

It hasn't been saved or checked since Lumtera was installed. Click Check new items on the Overview, or Check on its row in the Content report.

Results didn't change after I changed a setting

Settings apply to the next check. Go to the Overview and click Check all content again.

A result is wrong

First, check it's not a Needs review item. Those are things a person has to decide, and dismissing them is expected. If a check is definitely wrong:

• Dismiss the item with a reason, so it stops appearing.
• Tell us, with the check's ID and the HTML that triggered it. wp lumtera check is an easy way to reproduce it. See Support.

The alt text manager doesn't list a post that uses an image

The list comes from Lumtera's checks, so posts that haven't been checked don't appear. Run Check all content. Images inside blocks Lumtera can't update are listed separately. Add the alt text there in the editor.

Someone can't see the Accessibility menu or review mode

What each role can do is set under Accessibility → Settings → Permissions.

• The Overview, Content report and Dashboard widget need See reports and check the site. By default, that's editors and administrators.
• Review mode needs Review pages on the site, and the person must be able to edit that post. The Accessibility item only shows in the toolbar on the front end of a single post or page of a content type that's checked.
• The alt text manager needs the ability to upload files (Authors and up).
• Settings are for administrators only.

If the roles look right, check for a role editor plugin or custom code that removes the lumtera_view_reports, lumtera_dismiss_errors or lumtera_review_mode capability, or a filter such as lumtera_capability. See Roles & permissions.

"No connected AI provider can read images" or "can write text"

AI suggestions need WordPress 7.0 or later, with AI not switched off, and a connected provider under Settings → Connectors:

• Suggest alt text needs a model that can read images.
• Link text, headings and the summary need a model that can write text. Their switches are listed only once one is connected.

Lumtera re-checks what your provider can do every 10 minutes. See AI suggestions.

An AI suggestion button doesn't appear

• Check an administrator switched that feature on under Accessibility → Settings → AI.
• Suggest link text and Suggest heading only appear on the issues they help with, in the block editor sidebar. Suggest subheadings appears on long content with no subheadings.
• Draft a plain-language summary only appears under Reading level when the content reads above the target grade, in a supported language.
• The writing features work in the block editor only, not in Elementor or the classic editor.

"Too many AI requests in a short time"

Each person can make 30 AI requests in 10 minutes, across all AI features. Wait a few minutes. Developers can change the limit with lumtera_ai_rate_limit.

The weekly email summary doesn't arrive

• Check Send a weekly summary is on under Accessibility → Settings → Email summary, and look at the Next summary date shown there.
• If Lumtera Pro is active, the free summary isn't sent, and the section is hidden. Pro sends its own. See Weekly email summary.
• The email goes out with the first site visit after 9:00 on the chosen day. On a quiet site, see Scheduled tasks run late.
• If your site can't send mail, install an SMTP plugin and send a test from it. Check the spam folder too.

A site fix doesn't show on my site

• Clear your page cache and any CDN cache.
• Skip link: your theme must call wp_body_open(). No link is added if your theme already has one, or if it's a block theme, which gets WordPress's own.
• Zoom: if your theme prints its viewport tag after wp_head(), it wins. Ask the theme author to fix it.
• Link fixes apply only to post content, not menus, widgets or the footer.

Review mode can't find the post's content

Some themes display content in an unusual way. The Whole page tab still works. Use the editor sidebar for the content checks.

Scheduled tasks run late, or not at all

The free weekly email summary runs with WP-Cron. In Lumtera Pro Pro, alerts, the weekly summary, scheduled page checks, PDF checks and portfolio syncs run in the background with WP-Cron (or Action Scheduler, if WooCommerce is active). WP-Cron only runs when someone visits the site, and some hosts switch it off.

With Lumtera Pro, Tools → Site Health shows Lumtera Pro background tasks are running late when tasks are more than an hour late. The fix is a real server cron job that runs every five minutes:

*/5 * * * * wget -q -O - https://example.com/wp-cron.php?doing_wp_cron >/dev/null 2>&1

or, with WP-CLI:

*/5 * * * * cd /path/to/wordpress && wp cron event run --due-now >/dev/null 2>&1

Pro's background jobs also need an active license.

Alert emails don't arrive Pro

• Click Send a test alert under Accessibility → Settings → Alerts.
• If the test fails by email, your site can't send mail. Install an SMTP plugin and send a test from it.
• Remember alerts are only for new errors on published content. Drafts, bulk checks and imports don't send alerts. See How alerts work.

License problems Pro

See License & plans. Most often: the license has reached its site limit (deactivate it on an old site), or your host blocks outgoing requests to store.mantrabrain.com.

A client site won't connect to the portfolio Pro

See Troubleshooting connections.

Still stuck?

See Support.