Troubleshooting

The plugin's Help button (bottom right of every plugin page) has tips and FAQs for each page. This page collects the most common questions.

Connection

The connection test fails.
Check that the API key, Client GUID, engine name and environment all match the same engine in the Workbench, and that they were copied without extra spaces.

• "Rejected by HawkSearch" on the API key: the key is wrong or belongs to another engine.
• "Not recognized" on the Client GUID: the GUID doesn't belong to this engine.
• "Could not reach": the engine name or environment is wrong, or the host blocks outgoing connections. Ask your host to allow HTTPS (port 443) to *.hawksearch.com.

The Settings fields are locked.
The values are set in wp-config.php. See Configuration constants.

The Client GUID test says "OK (no index yet)".
The GUID is valid, but the engine has no index. Run a full reindex.

Fields and Facets

A field shows "error" after syncing.
Hover over the status to see HawkSearch's reason. A common cause is changing the type of a field that already exists in HawkSearch: change it back, or edit or delete the field in the Workbench and sync again.

My field changes don't show in HawkSearch.
Sync the fields, then run a reindex. Changes can take a few minutes to appear because of caching.

A facet doesn't appear on the site.
HawkSearch hides a facet when none of the current results has a value for it. Check that the field is indexed, run a reindex, and wait a few minutes for caching. For example, a facet on a blog-only field never shows for product searches.

Products and posts appear in tabs.
This is intended when both are indexed. See Tabbed Results.

Indexing

The item counts on the Home page differ.
Run a full reindex and wait a minute; HawkSearch's count lags slightly. If they still differ, check the content types on the Field Configuration page. Only published items are indexed, and products hidden from search (catalog visibility) are skipped.

A product or post isn't in the results.
Use Indexing → Preview an item with its ID or SKU. The preview says when an item isn't indexed and why (not published, not an indexed content type, excluded or hidden from search).

A reindex failed or stopped.
Search keeps using the previous index, so nothing is lost. Check the History table for HawkSearch's reason. If batches time out, lower Items per batch. A run with no progress for 30 minutes is stopped automatically when the next one starts.

The scheduled reindex is late or doesn't run.
WP-Cron only runs when someone visits the site. Ask your host to call wp-cron.php from a real cron job every 5 minutes. The Indexing page shows "Overdue" when a run is more than an hour late.

Search

The search page is empty, or the search box doesn't appear.
Check the status on the Search page. It needs:

• a published results page containing [hawksearch_results];
• a permalink structure other than "Plain" (Settings → Permalinks);
• Use HawkSearch for site search switched on (for the search boxes and ?s= searches).

Then clear any page cache or CDN cache. An empty results list with no error usually means nothing has been indexed yet.

Search results show the old WordPress results.
Switch on Use HawkSearch for site search, and clear page caches.

The search box is too narrow or looks different from the theme.
The search box takes the width of the theme's Search block. Adjust the block's width in the Site Editor, or add CSS (see Standard Template Changes).

Tracking

How do I check that tracking works?
Turn on Enable verbose logging on the Tracking page. Open the site in a private window, press F12 and open the Console. Search, click a result, view a product, add it to the cart and place a test order: each step logs a line starting with [HawkSearch tracking]. Events appear in the Workbench reports after a short delay.

No search or click events are recorded.
They come from the HawkSearch search box and results page, so switch on site search. Also check that Enable event tracking is on and that a cookie banner or privacy plugin isn't blocking cdn.jsdelivr.net or *.hawksearch.com.

Add to cart events arrive late.
That's by design: an add to cart is sent on the visitor's next page view, so it's captured however the product was added.

Recommendations

A recommendation widget is empty.
Strategies such as Also Bought, Also Viewed, Trending and Personalized are built from tracking data, so they stay empty until visitors have been active for a while. Add a Featured Items strategy as a fallback, check that tracking is on, and make sure the widget belongs to the same engine as your Client GUID.

A new widget isn't in the list.
Click Refresh list on the Recommendation Widgets page; the list is cached for five minutes.

Updating and Removing

How do I update the plugin?
Upload the new zip from Plugins → Add New Plugin → Upload Plugin and choose Replace current with uploaded. Settings are kept. See Updating the Plugin.

What happens when I deactivate the plugin?
Search returns to the standard WordPress search, scheduled reindexes stop and tracking stops. Settings are kept, so reactivating restores everything. Your index, fields, facets and widgets in HawkSearch are not changed.