Skip to content

Adam Greenwell

Troubleshooting Guide

Common issues and solutions for Lumenare Search.

Current release: 2.2.01

Open Settings → Lumenare Search for the grouped settings navigation. Search & Answers is under Configure search, and Index Management is under Maintain the index. On smaller screens, use the Settings section menu.

A PDF can look fine and still contain unusable text. Lumenare supports readable PDFs with valid text mappings. Damaged or missing mappings can make extraction return scrambled characters even though the page displays correctly. Scanned, image-only PDFs need OCR. If a document stops content analysis, use the PDF repair steps below. A service failure is a separate diagnosis; listed document IDs do not automatically mean those files are damaged.

Search Not Working

Symptoms: No results appear, search form doesn't respond, dropdown never shows.

Check Plugin is Enabled

  1. Go to Settings → Lumenare Search
  2. Ensure "Enable Plugin" is checked
  3. Save settings

Verify Index Exists

  1. Go to Index Management section
  2. Check "Indexed Posts" count
  3. If zero, click "Reindex All Content"

Check JavaScript Errors

  1. Open browser console (F12 → Console tab)
  2. Look for JavaScript errors
  3. Common issues:
    • jQuery not loaded
    • Script conflicts with other plugins
    • Theme compatibility issues

Verify AJAX is Working

  1. Check that admin-ajax.php is accessible
  2. Some security plugins block AJAX requests
  3. Whitelist lumenare_search action if needed

Check for Plugin Conflicts

  1. Deactivate other plugins one by one
  2. Test search after each deactivation
  3. Identify conflicting plugin

No Results Appearing

Symptoms: Search runs but returns no results for queries that should match.

Check Post Types

  1. Go to Settings → Lumenare Search → General
  2. Ensure desired post types are selected
  3. Reindex if you add post types

Verify Content is Published

Only published posts are indexed. Draft, pending, and private posts are excluded.

Check Minimum Characters

  1. Go to Settings → Lumenare Search → General
  2. Check Minimum Characters setting
  3. Ensure your query meets the requirement

Review Stop Words

Your search terms might be in the stop words list:

  1. Go to Settings → Lumenare Search → Search Quality → Stop Words
  2. Check if your search terms are listed
  3. Remove from stop words if needed
  4. Reindex after changes

Check Match Mode

If using "All (AND)" mode, all keywords must appear in content.

Try switching to "Any (OR)" mode for broader results.

Reindex Content

Content might not be indexed yet:

  1. Go to Index Management section
  2. Click "Reindex All Content"
  3. Wait for completion

Results Not Relevant

Symptoms: Wrong posts appearing first, irrelevant results ranking high.

Adjust Weights

If titles should matter more:

  1. Go to Settings → Lumenare Search → Search Quality
  2. Increase Title Weight
  3. Decrease Content Weight if needed
  4. Save settings and test again; reindex if you enabled a field that was previously weighted zero

Read the Tuning Guide →

Review Stop Words

Add common irrelevant words to stop words:

  1. Go to Settings → Lumenare Search → Search Quality → Stop Words
  2. Add words that appear in many posts but aren't useful for search
  3. Reindex after changes

Check Synonyms

Ensure synonyms are configured correctly:

  1. Go to Settings → Lumenare Search → Search Quality → Synonyms
  2. Each line should be comma-separated words
  3. Example: car, automobile, vehicle

Add Phrase Boosting

If specific phrases should rank higher:

  1. Go to Settings → Lumenare Search → Search Quality → Search Phrases
  2. Add important multi-word phrases
  3. Adjust Phrase Boost Multiplier if needed

If trending is causing irrelevant results:

  1. Go to Settings → Lumenare Search → Search Quality
  2. Uncheck "Enable Dynamic Trending Ranking"

Try Different Match Mode

Switch between "Any" and "All" modes:

  • Any (OR): More results, potentially less precise
  • All (AND): Fewer results, more precise

Content Analysis Not Ready

Symptoms: Analyze site content is disabled, the page reports pending passages, or meaning reranking falls back to local search.

Check Service, Approval and Saved Settings

  1. Activate the WordPress AI plugin and a connector that supports embeddings.
  2. Configure its credentials in Settings → Connectors. If Connector Approvals is enabled, approve Lumenare Search for that connector in Tools → Connector Approvals.
  3. Open Settings → Lumenare Search → Search & Answers → Advanced → AI service and model for content analysis.
  4. Choose a service, click Refresh model list, and choose a supported content-analysis model. An empty list means the installed connector reports no embedding models; a connector that writes answers may still have no embedding capability.
  5. Click Save Settings, then Refresh status beside the analysis controls. Unsaved service, model or content-analysis settings keep the start button disabled.

Status checks read local configuration and approval. They do not prove the account has quota or that the selected model will accept a request. Refresh model list contacts the service for model metadata, without sending site content or generating answers or vectors.

Run and Resume Content Analysis

Click Analyze site content in the same section. The browser prepares public, searchable posts in small batches, then sends missing or changed passages to your saved embedding service. Charges may apply. Keep the tab open and wait for the prepared-post and analyzed-passage progress to finish.

Use Pause to stop the browser run after its current batch. Resume analysis continues saved progress, including after reopening the page. Scheduled analysis may still run when meaning search is enabled. If a request fails, check the service, click Refresh status, and resume; the browser does not automatically retry paid batches. If another batch is running or the service is in a short error backoff, wait and refresh the status.

Read the error message before choosing a remedy. Service timeouts, rate limits, exhausted quota, credentials and model errors can stop a healthy batch. A document-read error means the file or its extracted text needs inspection; it does not by itself establish damaged PDF mappings. The listed document IDs identify sources to inspect. For a service failure, they can describe the entire submitted batch, including healthy files. Passage IDs identify prepared text passages, not Media Library attachment IDs.

Saving settings and opening this page do not start analysis. Preparing content does not enable meaning reranking, AI-written answers, public Ask Site or results-page cards; choose those separately.

Check the Selected Configuration's Coverage

The keyword index, prepared passages and stored analyses are separate. Reindex All Content maintains keyword search; it does not replace the analysis step for meaning reranking. Stored passage and analysis totals can include earlier configurations, so a non-zero total does not prove readiness for your selected service and model.

After content edits, check for pending analysis and run Analyze site content again. After changing the service, model, analysis size, passage settings or enabled content sources, save and start a run for the new configuration. Compatible analyses are reused. Stale passages and incompatible vectors are excluded from meaning reranking; visitor searches do not repair them.

Separate Database Errors from Connector Setup

If the message says analysis could not read its database tables, check the site error log. Older builds could report Illegal mix of collations when combining legacy WordPress tables with newer plugin tables. 2.2.00 fixes the post-type comparison used by content analysis without requiring a database collation conversion. Upgrade an older build first, then refresh status. Persistent database errors need their own diagnosis; changing connector approval will not repair a database read failure.

PDF Stops Content Analysis

Symptoms: Analysis reports that it could not read a document, identifies an attachment, or repeatedly stops while preparing that attachment's text.

Why a Readable Page May Have Unreadable Text

A PDF stores how a page is drawn separately from how its character codes map to searchable text. A file can display perfectly while copying, searching or extracting its words produces gibberish or missing letters. This can happen with damaged or missing text mappings, including in some older exports. Lumenare 2.2.01 fixes several parser compatibility problems and supports readable PDFs with valid text; it cannot reconstruct every damaged source file.

An image-only scan has no text to extract. Run OCR to add a searchable text layer, then check its accuracy. Lumenare does not perform OCR. A password restriction, missing upload, unreadable file permissions or a configured file-size limit can also cause a document-read failure.

Inspect and Repair the Affected Attachment

  1. Note the error category and listed document ID. Find that attachment in Media → Library; its edit URL contains post=ID. If the error is about the AI service instead, resolve that service problem first. Its IDs can name the whole healthy batch.
  2. Confirm the original upload exists, opens, is readable by WordPress and fits the configured maximum document size under Search Quality → Document Indexing. Check access or encryption restrictions before assuming the text is damaged.
  3. Use the attachment's Test Parse action and read the extracted text preview. Also copy a few sentences from the PDF into a plain-text editor. Check that letters, digits and words match the visible page. A bad copy/paste result is a useful clue; the parser preview is the more relevant check for indexing.
  4. Back up the original. If its text mappings are damaged, re-export from the original document with a searchable text layer, or repair that layer with a PDF tool. If it is a scan, OCR it. Review the resulting words and layout. Replace the file behind the same Media Library attachment using your site's supported replacement process so the attachment ID and links remain intact.
  5. Run Test Parse again. Once it returns readable text, open Search & Answers → Advanced → AI service and model for content analysis, click Refresh status, then Resume analysis. The current run repairs affected unusable cached text and passages where possible and reuses unrelated compatible analyses. A full-site restart is not normally needed for an attachment repaired in place.

Keep an unresolved document visible until it is repaired or deliberately removed from the configured content scope. Repeatedly resuming the same damaged file will not repair its source mappings, and an unresolved document is not counted as successfully analyzed.

If You Do Not Need PDF Content Included

Under Search Quality → Document Indexing, deselect PDF in Document MIME Types to Index while leaving the other document formats you want selected. If PDF is your only selected format, turn off Index Document Content instead; an empty format list uses the default supported formats, so clearing every checkbox does not disable document indexing. Turning off Index Document Content omits extracted text from all document formats. These controls affect the whole selected type or document scope; they are not an individual-file exclusion switch. Save the settings, then start Analyze site content for the changed configuration. Changing the scope stops the old run; Resume analysis is for a run whose saved configuration still matches.

This intentionally reduces the content available to search and answers. Prefer repairing the attachment when its text should remain searchable. Do not delete a public upload just to clear the analysis error.

Answers Missing or Only Ordinary Results Appear

Symptoms: Search finds posts, but there is no written answer or answer card.

Check Answer Style and Placement

In Search & Answers → Answers, choose Sources and cited excerpts or explicitly opt into AI-written answers with citations and save. AI writing needs WordPress 7.0 or newer with AI Client support and an approved, configured text-generation connector. The content-analysis model is a separate embedding choice.

In Search & Answers → Placement, enable public Ask Site and results-page answer cards independently. Cards can be enabled while public Ask Site stays off. Check Search Profiles and the surface table for overrides that change placement or answer style for the search you are testing.

Check Evidence and the Search Surface

Sources-only answers need a supporting passage from current public content. A matching title, taxonomy or similarity score alone is insufficient. Opted-in AI writing can also assess a small bundle of retrieved public passages, with checked citations and supporting quotes. Preparing embeddings improves eligible result ordering; it does not make every question answerable or find articles outside the existing keyword candidates.

Results-page cards appear once on the first page of a Lumenare HTML search. They do not appear in the live dropdown, later results pages, secondary queries, feeds or REST responses. A custom theme must use a supported main-loop or inherited Query-block hook for automatic card placement.

When a recognized question lacks enough evidence, enabled first-page cards show a clear no-answer message while keeping ordinary results and pagination available. An ordinary keyword search without answer evidence keeps its results without that question notice. If AI support is unavailable, a request fails, or its citations are invalid, Lumenare uses a supported cited excerpt when available. Results-page cards show their no-answer notice when no supported fallback is available. If the Ask Site form is empty after failed generation, check the provider status and site error log.

Live Search Dropdown Not Appearing

Symptoms: Typing in search doesn't show dropdown results.

Check JavaScript

  1. Open browser console (F12)
  2. Look for errors
  3. Ensure jQuery is loaded

Verify jQuery

Lumenare Search requires jQuery. Some themes disable it.

  1. Check theme settings for jQuery options
  2. Try switching to a default theme temporarily

Check AJAX URL

  1. Verify admin-ajax.php is accessible
  2. Try visiting: yoursite.com/wp-admin/admin-ajax.php
  3. Should return "0" (not an error page)

Review Minimum Characters

  1. Ensure you've typed enough characters
  2. Default is 3 characters
  3. Check setting in Settings → Lumenare Search → General

Check Browser Compatibility

  1. Test in different browsers (Chrome, Firefox, Safari)
  2. Some browser extensions block scripts

Clear Cache

  1. Clear browser cache
  2. Clear WordPress cache (if using caching plugin)
  3. Clear CDN cache if applicable

Index Not Updating

Symptoms: New posts don't appear in search results.

Check Post Status

Only published posts are indexed automatically. Drafts, pending, and private posts are excluded.

Verify Post Type

  1. Ensure post type is selected in Settings → Lumenare Search → General
  2. Custom post types must be explicitly enabled

Manual Reindex

  1. Go to Index Management section
  2. Use Partial Reindex → Index Only New Posts
  3. Or click "Reindex All Content" for full rebuild

Automatic Reindex

If automatic new-content reindexing is enabled:

  1. Check the next scheduled run in Index Management
  2. Review the last run status and continuation message
  3. Confirm WP-Cron is running on the site
  4. Run a manual partial reindex to catch up while investigating cron

Check for Errors

  1. Enable WP_DEBUG and WP_DEBUG_LOG in wp-config.php
  2. Check /wp-content/debug.log for indexing errors

Database Permissions

Ensure WordPress has write access to database tables.

Performance Issues

Symptoms: Slow search, site slowdown during indexing.

Reduce Index Scope

  1. Go to Settings → Lumenare Search → General
  2. Limit post types being indexed
  3. Only index post types that need search

Increase Stop Words

More stop words = smaller index:

  1. Go to Settings → Lumenare Search → Search Quality → Stop Words
  2. Add common words that don't need indexing
  3. Reindex after changes

Disable Fuzzy Matching

Fuzzy matching is more resource-intensive:

  1. Go to Settings → Lumenare Search → Search Quality
  2. Uncheck "Enable Fuzzy Matching"

Limit Dropdown Results

  1. Go to Settings → Lumenare Search → Display
  2. Reduce Dropdown Results (e.g., from 10 to 5)

Use Partial Reindex

Instead of full reindex, use partial options:

  1. Index only new posts
  2. Index specific post types
  3. Index by date range
  4. Enable automatic new-content reindexing for ongoing catch-up work

Optimize Database

Run database optimization tools:

  • phpMyAdmin optimize
  • WP-CLI: wp db optimize
  • Database optimization plugins

Security Filtering Too Aggressive

Symptoms: Legitimate searches are being blocked.

Review Blocked Characters

  1. Go to Settings → Lumenare Search → Advanced → Blocked Characters
  2. Check if legitimate characters are blocked
  3. Remove characters needed for your content

Check Blocked Patterns

  1. Go to Settings → Lumenare Search → Advanced → Blocked Patterns
  2. Review regex patterns
  3. Adjust patterns that cause false positives

Temporary Disable

For testing only:

  1. Go to Settings → Lumenare Search → Advanced
  2. Uncheck "Enable Security Filtering"
  3. Re-enable after testing!

Check Security Logs

  1. Enable "Enable Security Logging" in settings
  2. Review what's being blocked
  3. Identify false positives

Weighting Changes Not Taking Effect

Symptoms: Changed weights but results are the same.

Reindex Required

Weights are applied to stored field counts at query time. Changing an already enabled field from one positive weight to another does not require a reindex.

Reindex if you enabled a field that was weighted zero when content was indexed, or changed what content is extracted, such as stop words, post types, indexed custom fields or document settings. Use Index Management → Reindex All Content for a full rebuild.

Clear Cache

After reindexing:

  1. Clear WordPress cache
  2. Clear browser cache
  3. Test search again

Check Settings Saved

  1. Go to Settings → Lumenare Search → Search Quality
  2. Verify weights show expected values
  3. Save settings again if needed

Verify Weight Values

Weights are non-negative integers. A value of zero disables that field's contribution.

Check Active Profiles

Profile overrides can adjust ranking settings for specific search surfaces. Check Settings → Lumenare Search → Search Profiles if the frontend, shortcode, block, or Abilities API route behaves differently.

Taxonomy Terms Not Boosting Results

Symptoms: Category/tag matches not ranking higher.

Check Taxonomy Weights

  1. Go to Settings → Lumenare Search → Search Quality → Taxonomy Term Weighting
  2. Ensure weights are set (not 0)
  3. Default: category=5, tag=3

Verify Taxonomy Exists

  1. Check that taxonomies are registered
  2. Verify terms exist and are assigned to posts

Check Term Matching

Terms must match keywords exactly or partially. The keyword "security" would match a category named "Security" or "Website Security".

Reindex After Weight Changes

Positive-to-positive taxonomy weight changes take effect at query time. Reindex when enabling taxonomy content that was excluded by a zero weight during indexing, or when changing which content is indexed.

Symptoms: Trending boost not affecting results.

  1. Go to Settings → Lumenare Search → Search Quality
  2. Check "Enable Dynamic Trending Ranking"
  3. Save settings

Trending scores are calculated daily (2 AM by default). New installations need time to accumulate search data.

Check Minimum Searches

  1. Go to Settings → Lumenare Search → Search Quality
  2. Check Minimum Searches for Trending
  3. Queries need this many searches to become trending
  4. Default: 5 searches

Adjust Boost Strength

If trending influence is too weak:

  1. Increase Trending Boost Strength
  2. Default: 0.5, try 1.0 for stronger effect

Check that the trending table exists:

  1. Access your database via phpMyAdmin
  2. Look for wp_lumenare_search_trending table
  3. If missing, deactivate and reactivate plugin

Widget/Shortcode Not Working

Symptoms: Search form doesn't appear or function.

Check Widget Placement

  1. Go to Appearance → Widgets
  2. Verify widget is added to a widget area
  3. Check if widget area displays on your pages

Verify Shortcode Syntax

Use exactly: [lumenare_search]

Common mistakes:

  • Wrong brackets: (lumenare_search)
  • Wrong name: [lumenare-search]
  • Extra spaces: [ lumenare_search ]

Check Theme Compatibility

  1. Switch to a default theme (Twenty Twenty-Four)
  2. Test search
  3. If working, issue is theme-related

Review JavaScript Errors

  1. Open browser console (F12)
  2. Check for errors when page loads
  3. May indicate script conflicts

Symptoms: The Lumenare Search Trends widget or block renders no public terms.

Check Analytics Volume

Latest searches require repeated successful queries by default so one-off private searches are not promoted publicly.

Check Zero-Result Filtering

Disable Hide zero-result searches only if your analytics policy allows raw latest-query display.

Trending scores are calculated daily via WordPress cron. New installs need enough search history before the public trending list has data.

Configure An Empty Message

Set an empty message in the widget or block if the layout should show a placeholder before enough search data exists.

Database Table Issues

Symptoms: Errors about missing tables, database errors in logs.

Deactivate and Reactivate

This recreates database tables:

  1. Go to Plugins
  2. Deactivate Lumenare Search
  3. Reactivate Lumenare Search

Check Database Permissions

Ensure WordPress user can create tables:

  1. Check MySQL user privileges
  2. Should have CREATE, ALTER, INSERT, UPDATE, DELETE

Review Database Prefix

If using custom prefix, tables should be {prefix}lumenare_search_index, etc.

Manual Table Check

Access database via phpMyAdmin and verify tables exist:

  • wp_lumenare_search_index
  • wp_lumenare_search_chunks – Prepared passages for optional meaning search
  • wp_lumenare_search_vectors – Locally stored content analyses
  • wp_lumenare_search_analytics
  • wp_lumenare_search_trending
  • wp_lumenare_search_clicks
  • wp_lumenare_search_result_impressions
  • wp_lumenare_search_import_runs
  • wp_lumenare_search_suggestion_terms
  • wp_lumenare_search_opportunity_actions
  • wp_lumenare_search_query_promotions
  • wp_lumenare_search_event_queue
  • wp_lumenare_search_security_logs
  • wp_lumenare_search_ability_logs

Index Schema Notices

If Lumenare reports failed index writes, schema repair, or a reindex-required notice, run the recommended reindex first. If the notice returns, check database permissions and debug.log for the hard-error message.

Contact Hosting

Some hosts restrict table creation. Contact support if tables can't be created.

Ajax Search Pro Migration Issues

Symptoms: Imported ASP history appears mixed with native Lumenare analytics, or leftover ASP tables/options remain after migration.

Use Source Filters

Search Intelligence and Search Imports include source filters so you can separate native Lumenare data from imported Ajax Search Pro history.

Preview Cleanup

Use the guarded cleanup preview before deleting ASP tables or options. For large sites, run:

wp lumenare cleanup asp --dry-run

Only add --yes after the dry run shows the intended cleanup set.

Still Having Issues?

If you've tried these solutions and still have problems:

  1. Check the WordPress.org forums – Search for similar issues
  2. Post a support request – Include:
    • WordPress version
    • PHP version
    • Plugin version
    • Error messages (if any)
    • Steps to reproduce

WordPress.org Support Forums →

Search & Answers

Back to Documentation Index →