Troubleshooting
Fixing common WidgetCore problems — installation and activation, missing widgets in the editor, search returning no results, styling issues, FAQ behaviour, updates and performance.
This page collects the problems reported most often, with the quickest way to confirm each cause. Work top to bottom: most issues are resolved in the first two sections.
Installation and activation
| Symptom | Cause | Fix |
|---|---|---|
| The plugin does not appear in the list | Wrong folder nesting | The path must be wp-content/plugins/widgetcore/widgetcore.php |
| “Requires Elementor” notice | Elementor inactive | Activate Elementor first |
| PHP version error | PHP below 7.4 | Upgrade PHP in your hosting panel |
| White screen after activating | A PHP fatal from another plugin | Enable WP_DEBUG, read the error, deactivate the conflicting plugin |
| The version in the list is old | Browser or object cache | Hard refresh; clear the site cache |
Widgets missing in the editor
Confirm Elementor is active
The widget category is registered on an Elementor hook; without Elementor nothing appears.
Search the panel
Type “WidgetCore”, “faq” or “search” in the widget panel search.
Check for a category filter
Some themes or addons hide categories; look for a filter in the panel.
Hard refresh the editor
Ctrl + Shift + R (Cmd + Shift + R on macOS) clears the editor cache.
Regenerate Elementor CSS
“Elementor → Tools → Regenerate CSS & Data”.
| Symptom | Cause | Fix |
|---|---|---|
| The category exists but is empty | A fatal error while loading a widget class | Check debug.log |
| The widget appears but shows nothing in preview | The preview assets did not load | Refresh; check that wgcr-search styles/scripts are requested |
| Another plugin's category replaced ours | A conflict on category registration | Deactivate the other plugin to confirm |
Search returns no results
| Symptom | Cause | Fix |
|---|---|---|
| Nothing happens while typing | The query is shorter than 2 characters | Type at least two characters (minChars) |
| “No results found.” for a term you know exists | The Source is a different post type | Set “Source” to the right post type, or “All post types” |
| No results for a draft or private post | Only publish and non-password posts are searched | Publish the post |
| No results with a category filter | The term ids do not match, or terms_op is wrong | Check the ids and whether you want include or exclude |
| The panel shows “Error fetching results.” | The REST request failed | See the quick REST diagnosis below |
| Results appear but the count is wrong | Cached headers | Exclude the route from page caching |
Quick REST diagnosis
Open the endpoint directly in a browser:
https://example.com/wp-json/wgcr/v1/search?q=test&limit=5| Response | Meaning | Fix |
|---|---|---|
| A JSON array of results | The endpoint works; the problem is in the widget settings | Check “Source”, “Date filter” and the term filters |
[] (empty array) | The query matched nothing | Try another term, or widen the source |
rest_invalid_param | q is missing or shorter than 2 characters | Add a longer q |
rest_cannot_access | The REST API is blocked | Check security plugins and server rules |
| A 404 page | Permalinks are not set | “Settings → Permalinks”, save once |
| A PHP error page | A server-side fatal | Read debug.log |
Then repeat the same request from the browser's network tab while typing in the widget, and compare the URL, the status and the response headers.
Appearance and styling
| Symptom | Cause | Fix |
|---|---|---|
| The widget looks unstyled | search.css did not load | Clear caches; check the network tab for search.css?ver=0.0.7 |
| Old styles after an update | A cached stylesheet | Purge the cache; the version query string forces a new fetch |
| Columns collapse to one | The viewport is below 782px | Expected responsive behaviour |
| Masonry looks uneven | Masonry and equal height are both on | Enable only one |
| The panel is too narrow in List mode | The container width limits it | Widen the container, or use the “as wide as the field” snippet on the styling page |
| A custom template is unstyled | The template CSS did not load | Regenerate Elementor CSS and clear caches |
FAQ widget
| Symptom | Cause | Fix |
|---|---|---|
| Items do not open at all | The widget script did not run | Check for JS errors in the console; clear caches |
| A long answer is cut off | The script is not running, so the no-JS cap (max-height: 640px) applies | Fix the script loading; with it running, the height is measured from the content |
| Two items open at once | The mode is “Toggle” | Switch to “Accordion” |
| The icon does not rotate | The icon type is not compatible | Use “Plus”, “Chevron” or a custom icon with the rotation control |
No FAQPage schema | The control is off, or this is the second FAQ widget on the page | Enable the control; keep one schema-emitting widget per page |
| The heading level looks wrong in the outline | The “Question heading tag” control | Choose H2, H3 or H4 to fit your page structure |
Updates
| Symptom | Cause | Fix |
|---|---|---|
| A new release never appears | WordPress checks every 12 hours | Click the “Check for updates” link on the Plugins screen |
| Download fails on a private repository | No credentials | Define WGCR_GITHUB_TOKEN in wp-config.php |
| cURL error 28 / timeout | Outbound requests blocked | Allow api.github.com and github.com in the firewall |
| “View details” is empty | The release has no notes | Add release notes on GitHub |
| The plugin folder changed name | The release ZIP structure | The package must contain a widgetcore/ folder |
Full details on the updates page.
Performance
| Symptom | Cause | Fix |
|---|---|---|
| Slow first keystroke response | A heavy query (rand, a big tax_query, an unindexed meta_query) | See the query and filters page |
| Large payloads | limit too high, or thumbnails on | Lower “Items per page”, or turn thumbnails off |
| Slow with a custom template | The template is rendered per result on the server | Keep 6 to 9 items per page |
| Many image requests | Thumbnails at full size | Use a smaller registered image size in a custom template |
| Repeated identical queries | No caching | Cache the route response for anonymous visitors |
Quick diagnosis checklist
Elementor is active and the category is visible
The endpoint answers: /wp-json/wgcr/v1/search?q=test
The widget's Source matches the content you expect
No JavaScript errors in the browser console
Caches cleared and the asset version is the current plugin version
debug.log has no fatal errors
If all six pass and something still misbehaves, note the plugin version, WordPress version, Elementor version and the exact steps, then open an issue on the GitHub repository — that information is what makes a report actionable.