Skip to content
Forum Fortress
Get started free

Troubleshooting

Use this guide to diagnose installation and runtime problems.

Before changing settings, note the forum URL, platform and plugin version, the approximate time of the problem and the exact error text. Copy the Decision Reference if one is shown. Include these details when contacting support.

Installation Issues

Connection Test Fails

Symptoms: - Plugin reports "connection failed" or similar - Timeouts during setup - HTTP error codes in plugin logs

Solutions:

  1. Check outbound HTTPS access
  2. Ensure your server can make HTTPS requests to *.ffapi.net on port 443

  3. Test with: curl -v https://api.ffapi.net/health from your server

  4. Firewall and security software

  5. Allow outbound connections to *.ffapi.net
  6. Check hosting firewall, WAF, and security policies

  7. Ask the host to test or allow the egress rule rather than weakening security controls on a live site

  8. DNS resolution

  9. Verify your server can resolve api.ffapi.net

  10. Test with: nslookup api.ffapi.net or dig api.ffapi.net

  11. Proxy and reverse proxy

  12. Configure proxy settings if your server uses one

  13. Check if hosting provider requires specific egress configuration

  14. Rate limiting

  15. Some hosts aggressively rate-limit outbound connections
  16. Contact hosting support if you see HTTP 429 errors

Plugin Installation Fails

XenForo: - Ensure you have super administrator access - Check the XenForo is version 2.x - Verify the ZIP file isn't corrupted (re-download if needed)

phpBB: - Follow phpBB’s extension install flow: unzip into ext/, then enable in Customise → Manage extensions (see phpBB install guide) - Confirm files were extracted to the correct ext/ directory path and folder layout was preserved (ext/forumfortress/protect/...) - Ensure you have ACP administrator access

Invision Community: - Confirm you have administrator access - Check Invision version compatibility - Ensure the upload completed successfully

Discourse: - Confirm the Forum Fortress clone line is in the existing hooks.after_code command list in /var/discourse/containers/app.yml - Confirm the clone destination is discourse-forum-fortress - Rebuild with cd /var/discourse && ./launcher rebuild app, then inspect the rebuild output for plugin errors - Hosted Discourse plans that do not allow arbitrary third-party plugins require approval from the hosting provider

NodeBB: - Confirm NodeBB is 4.16 or later in the 4.x series and is running Node.js 22 or newer - Search Extend → Plugins for Forum Fortress, or install the exact nodebb-plugin-forum-fortress package from npm - Activate the plugin, run ./nodebb build, restart NodeBB and reopen the ACP

Runtime Issues

Plugin Lost Connection After Reinstall

Symptoms: - Forum Fortress plugin shows connection or authentication errors - You reinstalled the forum software or the plugin files - Bootstrap no longer returns an API key

Solution - portal “Reset key” window (registered sites):

  1. Sign in to the portal with the same email used for your site.
  2. On the Overview dashboard, scroll to Reinstalling your forum? at the bottom of the page.
  3. Click Reset key. The card will show: Accepting a new plugin install until … (10-minute window).
  4. Within those 10 minutes, enable the plugin on your forum and let it connect (or run bootstrap from the plugin admin screen).
  5. The plugin receives a fresh API key for your domain. Complete plugin registration in your forum admin if prompted.

Important: - The reset window lasts 10 minutes from when you click the button. - Only one active window per site; open it immediately before reconnecting the plugin. - You must be signed into the portal for the site you are reconnecting. - This reset-window flow is for sites already associated with a portal account. A new or anonymous site should use the plugin's normal bootstrap, connection test and Open Forum Fortress flow instead. Contact support if a registered site still cannot reconnect.

If the window expires: - Return to the portal Overview and click Reset key again to open a new 10-minute window.

Forum Not Appearing in Portal

Causes: - Forum not connected to your portal account - Using different email address for portal vs forum connection - Connection process was incomplete

Solutions:

  1. Open the portal from the plugin
  2. Run bootstrap or Connection test in the forum's Forum Fortress settings
  3. Select Open Forum Fortress so the secure handoff uses the selected forum

  4. If you need multi-forum or account features, complete account association in the plugin

  5. Re-connect the forum

  6. In the forum's Forum Fortress settings, run bootstrap or the connection test again
  7. Use Complete registration or Register Site if the forum should be attached to an existing account

  8. Check for confirmation messages

  9. Check forum URL

  10. Ensure the forum URL in settings matches what visitors actually use
  11. Include or exclude www as appropriate
  12. Use HTTPS if that's how users access your forum

Protection Not Working

Symptoms: - Obvious spam getting through - No activity showing in portal - Plugin appears inactive

Troubleshooting:

  1. Verify plugin is enabled
  2. Check that Forum Fortress is active in your forum's plugin/extension list

  3. Look for Forum Fortress settings or configuration options

  4. Check connection status

  5. Run connection test from plugin settings

  6. Look for error messages or warnings in plugin interface

  7. Review protection settings

  8. Confirm protection is enabled for the actions you want covered

  9. Check if forum is in a testing or disabled state

  10. Monitor for recent activity

  11. Visit portal Overview to see if any checks are being performed
  12. Even allowed actions should show some activity

Moderation Queue Issues

Symptoms: - Moderation actions not syncing - Moderation actions not taking effect - Duplicate items appearing

Solutions:

  1. Clear browser cache
  2. Log out of the portal, clear browser cache, log back in

  3. Try an incognito/private browsing window

  4. Check forum integration

  5. Verify the forum's moderation system is working normally

  6. Test the relevant moderation action directly in the forum admin panel

  7. Review item details

  8. Check if items have specific requirements or restrictions

  9. Look for any error messages in the portal interface

  10. Contact support

  11. If items remain stuck, use portal Contact with specific examples
  12. Include timestamps and affected usernames or content

Common Error Messages

HTTP 403 Forbidden

Cause: Permission or authentication issue

Solutions: - Check if your hosting provider blocks certain outbound requests - Verify Forum Fortress settings have correct forum URL - Re-connect forum to portal if authentication expired

HTTP 429 Too Many Requests

Cause: Rate limiting by hosting provider or security software

Solutions: - Contact hosting support about outbound rate limits - Check WAF and security software settings - Verify you're not making duplicate concurrent requests

HTTP 500 Server Error

Cause: Server-side configuration issue

Solutions: - Check forum error logs for detailed messages - Verify PHP version and required extensions are installed - Ensure adequate server resources (memory, CPU) - Contact hosting support with the exact error and time if the forum log does not identify the cause

SSL/TLS Errors

Cause: HTTPS connection problems

Solutions: - Verify your server has up-to-date SSL/TLS libraries - Check if hosting provider blocks certain SSL protocols - Ensure system time is correct (SSL certificates are time-sensitive)

Performance issues

Slow forum response

  1. Run the plugin connection test and record its timings or error.
  2. Check whether the delay affects only protected actions or every forum page.
  3. Review forum logs and server CPU and memory at the recorded time.
  4. Note any other changes made at about the same time.

If only protected actions are slow, send these details, the forum version and the plugin version to support.

Platform-Specific Issues

XenForo Issues

Add-on Options Missing: - Confirm add-on is fully installed and enabled - Check if you need to rebuild caches - Look for XenForo version compatibility issues

Moderation Integration: - Review XenForo moderation settings - Check if other add-ons conflict with Forum Fortress - Verify user permissions for moderation features

phpBB Issues

Extension Not Listed: - Verify correct extraction path in ext/ directory - Ensure all files were extracted with correct permissions - Enable the extension in Customise → Manage extensions after upload - Check phpBB error logs for specific messages

Update, reinstall, or remove: - Update: disable in Manage extensions, delete ext/forumfortress/protect/, upload the new package to ext/, enable again (install guide) - Reinstall: disable, delete files (and extension data for a clean slate), then repeat install steps (install guide) - Remove completely: disable, delete extension data, delete files (install guide)

Hooks Not Working: - Confirm phpBB version compatibility - Check if template modifications are required - Review extension configuration settings

Invision Community Issues

Upload Problems: - Ensure application upload completed successfully - Check file permissions in Invision directory - Verify Invision version compatibility

Integration Issues: - Review Invision hook system for conflicts - Check application settings and configuration - Verify administrator permissions

Discourse Issues

Plugin or dashboard not listed: - Confirm the repository URL and clone destination in app.yml, then rebuild Discourse - Open Admin → Plugins → Forum Fortress → Dashboard after the rebuild - Check the rebuild output and Discourse logs for plugin load or compatibility errors

First connection takes longer than an ordinary check: - Allow up to 30 seconds for the first bootstrap and connection test - Confirm the Discourse host can make outbound HTTPS requests to *.ffapi.net - Keep fail-open enabled initially so a temporary network failure does not prevent ordinary forum activity - See the Discourse installation guide for update, uninstall, and privacy details

NodeBB Issues

Plugin or Forum Fortress menu is missing: - Confirm nodebb-plugin-forum-fortress appears in ./nodebb plugins - Activate it in Extend → Plugins or run ./nodebb activate nodebb-plugin-forum-fortress - Run ./nodebb build, restart the normal NodeBB service and refresh the ACP

Connection or first bootstrap fails: - Open Plugins → Forum Fortress, select Connection test and note the sanitized error - Confirm outbound HTTPS to *.ffapi.net and check the selected region - Enable plugin debug logging temporarily and inspect the NodeBB log; API keys are redacted - See the NodeBB installation guide for reinstall, removal and privacy details

Getting Help

When contacting support, include:

  • Forum URL (the public URL visitors use)
  • Forum platform and version (e.g., "XenForo 2.2.13")
  • Plugin/extension version (from plugin settings or file info)
  • Specific error messages (exact text, screenshots if helpful)
  • When the issue started (approximate date/time)
  • What you were trying to do when the problem occurred
  • Browser and device (if portal-related)

Portal Contact

Use Contact in the portal for account-specific help: portal.forumfortress.com

Before Contacting Support

  1. Try basic troubleshooting
  2. Connection test
  3. Clear browser cache

  4. Check obvious configuration issues

  5. Check service status

  6. Visit status.forumfortress.com for current service status and incident notices.

  7. Gather information

  8. Note exact error messages
  9. Document steps to reproduce the issue

  10. Check if issue affects all users or just specific cases

  11. Test in safe environment

  12. If possible, test with a staging/development copy of your forum
  13. Try disabling other plugins/extensions temporarily
  14. Test with default forum theme if applicable

Include the details above so support can investigate.