Contents

Troubleshooting — Plugixa FAQ

Common issues and how to fix them. If your problem isn’t here, collect the debug info at the bottom and contact support.

Plugin not appearing in admin

Symptom: You installed and activated the plugin but no Plugixa FAQ menu appears.

Causes & fixes:

  • User role — only users with manage_options see the admin menu. Grant the capability or use an admin account.
  • Another plugin is suppressing it — switch to a default theme and deactivate all other plugins to isolate.
  • Autoloader failed — check the error log for Class "PlugixaFaq\Plugin" not found. Delete vendor/ and re-download the plugin ZIP.

Shortcode prints as raw text

Symptom: The page shows [plugixa_faq] literally instead of FAQs.

Fixes:

  • Confirm the plugin is active: Plugins → Installed Plugins.
  • Check that quotes are straight (") not curly (""). The WP visual editor sometimes converts them — paste from a plain-text editor.
  • If you’re using a page builder, use the builder’s Shortcode widget, not a raw HTML block.

No FAQs displayed

Symptom: Empty space where the FAQ should be.

Run through this checklist:

  1. FAQs exist and are published — Plugixa FAQ → FAQs. Status must be published.
  2. Correct category slug — typos are the #1 cause. Compare the slug in Categories to the one in your shortcode.
  3. Content source matches the data — content_source="wordpress_posts" with no posts returns nothing.
  4. Language filter — if Multilingual is active, FAQs in other languages are hidden. Try language="en" explicitly.
  5. Fallback setting — with multilingual_fallback="hide", missing translations show nothing. Switch to default_language to show the default-language version.

Styling doesn’t match the view preview

Symptom: The view looks correct in the editor preview but different on the frontend.

Causes:

  • Theme CSS overrides — the theme’s CSS is more specific than the plugin’s. Use browser DevTools to find the overriding rule and add a fix in Settings → Custom CSS.
  • Disabled plugin CSS — check Settings → Advanced → Disable plugin CSS. If on, turn it off (unless you’re intentionally providing full custom CSS).
  • Stale cache — clear any caching plugin (WP Rocket, W3 Total Cache, Cloudflare, host-level page cache).

JavaScript error: “plugixaFaqSettings is not defined”

Symptom: Accordion doesn’t animate, or the console shows plugixaFaqSettings is not defined.

Fix: The plugin’s JS loaded before its inline wp_localize_script data. Causes:

  • Async/defer attribute added by an optimization plugin (WP Rocket, Autoptimize). Exclude plugixa-faq-accordion.js from async/defer in that plugin’s settings.
  • Custom theme JS bundling moved the script out of order.

Feedback widget not recording votes

Symptom: Visitors click but the counts don’t go up.

Checks:

  1. Feedback is enabled — Settings → Feedback → Enable feedback = on.
  2. Cooldown — you’re likely testing with the same browser/IP. Wait the cooldown window or clear cookies.
  3. reCAPTCHA — if enabled, check that site key and secret key are valid. Failed verification silently rejects votes.
  4. AJAX errors — open DevTools → Network → click a vote button. Look for a 403/500 from /wp-json/plugixa-faq/v1/feedback.

Multilingual migration did not run

Symptom: Existing FAQs have empty language_code, so they’re either always hidden or always shown regardless of language.

Fix:

  1. Go to Plugixa FAQ → Settings → Advanced → Re-run multilingual migration.
  2. Confirm. The backfill sets every NULL-language row to the site’s default language.

If that fails, reset the retry counter:

DELETE FROM wp_options WHERE option_name = 'plugixa_faq_upgrade_attempts';

Then retry the migration.

AI generator returns “API error”

Symptom: Clicking Generate returns API error: ...

  • 401 — API key is wrong or revoked. Regenerate in the provider dashboard.
  • 429 — rate-limited. Wait, or upgrade your provider plan.
  • 400 — prompt is too long. Lower the batch size or provide less context.
  • 5xx — the provider is down. Retry in a few minutes.

See AI Generator → Troubleshooting.

Admin login issue

Debug login screen

If you can’t access wp-admin due to a plugin-related fatal error:

  1. FTP/SSH into the site.
  2. Rename wp-content/plugins/plugixa-faq to plugixa-faq.disabled.
  3. Log in — the plugin is now deactivated.
  4. Rename back, then re-activate and check the error log.

HMR / dev server not loading assets

Symptom: Admin panel is blank or shows a loading spinner forever (development setup only).

  • Confirm the Vite dev server is running: cd assets/backend/app && npm run dev.
  • Confirm port 5173 is reachable.
  • If you’ve changed the port, update WP_PLUGIXA_HMR_URL (or the equivalent constant in includes/admin/class-hmr.php).

See Getting Started → Development.

WooCommerce tab not showing

Symptom: FAQs tab is missing from product pages.

  • WC is active — confirm Plugins screen.
  • Pro license is active — the integration is Pro-only.
  • Tab enabled — Settings → WooCommerce → Enable product FAQs = on.
  • FAQs assigned — pick FAQs via the product metabox. An empty tab is hidden automatically.
  • Theme override — some themes replace WC tabs entirely. Test with Storefront to confirm.

“Permission denied” on REST API

Symptom: REST calls return 403.

  • The endpoint requires manage_options. Log in as admin.
  • Nonce — custom front-end callers must include the wp_rest nonce in the X-WP-Nonce header.
  • Pro endpoints on a free install return 403 with a message pointing to the upgrade URL — that’s expected.

Symptom: #faq-5 anchors don’t scroll or you get a 404 when visiting an FAQ permalink.

  • Visit Settings → Permalinks and click Save without changing anything. This flushes rewrite rules.
  • Confirm permalink_structure is set in Plugixa FAQ → Settings → Permalinks.

Debug mode

Add this to wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Errors write to wp-content/debug.log. Reproduce your issue, then attach the relevant lines when contacting support.

Health check endpoint

GET /wp-json/plugixa-faq/v1/settings/health

Returns plugin version, DB version, active integrations, and any pending upgrade tasks. Public (no auth needed) — useful for external monitoring.

What to include in a support request

To get help fast, provide:

  1. Plugin version — from the Plugins screen.
  2. WordPress version, PHP version, MySQL version — from Tools → Site Health.
  3. Active theme and list of active plugins.
  4. The exact shortcode or steps to reproduce.
  5. Browser console output if the problem is frontend.
  6. Relevant debug.log excerpt if the problem is backend.

Quick Links

Plugin page Changelog