XenForo Admin Panel Works but the Forum Shows an Error: How to Find What Is Breaking the Frontend

You open your XenForo Admin Control Panel and everything appears normal. You can view users, add-ons, options and logs. But when you open the public forum, you see an error.

XenForo Beginner

You open your XenForo Admin Control Panel and everything appears normal.

You can view users, add-ons, options and logs.

But when you open the public forum, you see an error.

Depending on the failure, XenForo may display a generic message, an HTTP 500 response, a blank page or an error such as:

Oops! We ran into some problems.

This situation gives us an extremely useful clue.

If the XenForo Admin Control Panel works but the public forum does not, XenForo is not completely broken.

PHP can execute at least some XenForo code. The application can connect to the database. Authentication and the Admin Control Panel can load.

The failure is more likely to exist in something used primarily or exclusively by the public-facing application.

Possible causes include:

A frontend add-on
A broken style
A template modification
A PHP template-modification callback
A public route or controller extension
A widget
A navigation modification
An external API used on frontend pages
A cache problem
A damaged XenForo or add-on file
A web-server rule affecting friendly URLs
A permission or filesystem problem triggered only by frontend functionality

That is a much smaller troubleshooting area than “XenForo is broken.”

PRBLEM Principle: When one half of an application works, use the working half as evidence. Do not troubleshoot the entire stack as if nothing works.

Before You Change Anything

Do not begin by reinstalling XenForo.

Do not delete add-ons or database tables.

The working Admin Control Panel gives us access to useful diagnostic information, so preserve the current state while collecting evidence.

Before deeper troubleshooting, make sure you have recent backups of:

The XenForo database
The XenForo installation files
src/config.php
Custom styles
Custom templates
Third-party add-on files

If possible, reproduce risky tests on a staging copy.

Do not do these things yet

Do not reinstall XenForo.
Do not empty XenForo tables.
Do not uninstall add-ons during the first diagnostic pass.
Do not replace src/config.php randomly.
Do not clear every cache repeatedly without testing between steps.
Do not overwrite custom styles before making a backup.
Do not delete the faulting file just because an error log mentions it.

Step 1: Determine How Much of the Forum Is Broken

Do not assume every public XenForo route fails.

Test several URLs separately.

Forum index
A forum
A thread
A member profile
What’s new
Search
Login page
Registration page

Pattern A: Every public page fails

Investigate functionality loaded globally on the public application:

Add-on event listeners
Global template modifications
Navigation changes
Global widgets
Active style
Frontend bootstrap extensions

Pattern B: Only the forum homepage fails

Investigate:

Homepage widgets
Forum-list template modifications
Node-related add-ons
Custom homepage routes

Pattern C: Only threads fail

Look for add-ons and templates that interact with:

Posts
Reactions
Attachments
Signatures
Thread fields
Post rendering
Thread widgets

Pattern D: Guests see an error but logged-in users do not

Investigate:

Guest-specific widgets
Advertising integrations
Guest page caching
Permission-based add-on code
Cookie or consent integrations

Pattern E: Only one style fails

This immediately moves styles and template modifications near the top of the suspect list.

PRBLEM Diagnosis: Do not ask only whether “the forum” works. Identify the smallest route, user type or style that reproduces the failure.

Diagnosis Path A: Read XenForo’s Server Error Log First

Because the Admin Control Panel still works, your first major advantage is access to XenForo’s own logs.

Open the Logs section in the Admin Control Panel and find the Server error log.

Now reproduce the frontend error.

Immediately return to the error log and look for a new entry with the same timestamp.

XenForo can record useful information including:

The exception type
The file where the error was detected
The line number
A stack trace
The URL being requested
Request-state information

This information is often enough to identify whether an add-on, template callback or XenForo component is involved.

Example

ErrorException: Some error message
src/addons/Vendor/Product/Listener.php:87

Stack trace:
#0 ...
#1 ...
#2 ...

The important clue is:

src/addons/Vendor/Product/

This strongly suggests that the add-on identified by that path participates in the failure.

It does not automatically prove the add-on is defective.

Another component may have passed unexpected data into it.

But you now have a specific component to investigate.

PRBLEM Principle: A stack trace is a route through the failure. Follow the first relevant third-party component instead of reading only the final error message.

Diagnosis Path B: A Frontend Add-on Is Failing

This is one of the most common explanations for a working Admin Control Panel and broken public forum.

An add-on may extend public XenForo controllers, templates, entities or listeners without affecting the ACP route you are using.

Examples include add-ons for:

Thread enhancements
Post displays
Advertisements
Member profiles
Widgets
Navigation
SEO
Social sharing
Reactions
Custom nodes

Start with the error log

If the stack trace contains an add-on path, disable that add-on through the Admin Control Panel.

Do not uninstall it.

Then reopen the exact public URL that failed.

If the page now loads, you have strong evidence that the add-on participates in the problem.

If the error log does not identify one add-on

Use controlled isolation.

If many add-ons are installed, use the half-split method.

24 third-party add-ons
        ↓
Disable 12
        ↓
Test public forum
        ↓

Forum works?
YES → suspect is in disabled group
NO  → suspect is in enabled group

        ↓
Split suspicious group again
        ↓
Repeat

This is faster than testing twenty-four add-ons individually.

Use staging when possible because disabling add-ons on a production forum may temporarily remove functionality.

Do not uninstall while testing

XenForo add-on uninstall routines can remove data belonging to the add-on.

For diagnosis, disable first.

PRBLEM Rule: Disable to test. Uninstall only when you have already decided that the add-on should be removed and its data consequences are understood.

Diagnosis Path C: Temporarily Disable Add-on Listeners

If frontend failures make normal add-on isolation difficult, XenForo provides an emergency configuration switch for code event listeners.

Open:

src/config.php

Make a backup of the file.

Temporarily add:

$config['enableListeners'] = false;

Save the file and test the public forum again.

If the forum suddenly loads, third-party listener code becomes a strong suspect.

However, this test has an important limitation.

This is not the same as disabling all add-ons through the Admin Control Panel.

Use it as an emergency recovery or isolation clue.

Then remove the temporary configuration line and disable suspected add-ons normally through XenForo.

Do not leave listeners disabled permanently because much third-party functionality will no longer execute correctly.

Diagnosis Path D: A Template Modification Callback Is Breaking the Frontend

XenForo add-ons can modify templates automatically.

Most template modifications are straightforward replacements, but modifications can also use PHP callbacks.

If one of those callbacks fails, frontend rendering can break even while the Admin Control Panel remains accessible.

XenForo provides a configuration switch that disables template-modification callbacks.

For a controlled diagnostic test, add to:

src/config.php

the following:

$config['enableTemplateModificationCallbacks'] = false;

Then test the failing public page.

If it suddenly renders, investigate add-ons that use PHP callback-based template modifications.

Remove the temporary configuration change after diagnosis.

PRBLEM Diagnosis: If disabling ordinary listeners changes nothing but disabling template-modification callbacks restores the page, the failure may exist specifically in the rendering-modification layer.

Diagnosis Path E: The Active Style Is Broken

If the Admin Control Panel works but the frontend fails, the active public style deserves careful investigation.

The ACP uses its own administrative interface and does not necessarily render through the same customized frontend templates.

A style problem can therefore break the public forum while leaving administration available.

Test with another style

If you have a clean or minimally modified XenForo style available, temporarily test the affected page using that style.

If the public forum works with the clean style but fails with your customized style, focus on:

Edited templates
Custom LESS/CSS
Style-specific template modifications
Custom JavaScript
Outdated parent/child style changes

Do not immediately delete the broken style.

The difference between the working and failing style is valuable evidence.

Was XenForo recently upgraded?

Custom templates can become outdated after XenForo changes its default templates.

If the problem appeared after an upgrade, review customized templates and merge conflicts before replacing the entire style.

Diagnosis Path F: A Template Edit Contains a Rendering Error

A single template edit can affect every public page if the modified template is globally included.

Common examples include changes to:

Page container templates
Header templates
Navigation templates
Footer templates
Macros used by many pages

Ask what changed immediately before the failure.

Forum works
        ↓
Template edited
        ↓
All frontend pages fail
        ↓
ACP still works

That timeline makes the template change a high-value suspect.

Revert the most recent edit first

If the error began immediately after one template modification, undo that specific change before touching unrelated templates.

Do not reset the entire style unless necessary.

One controlled rollback gives you more information than deleting dozens of customizations simultaneously.

Diagnosis Path G: A Widget Is Failing on the Public Page

Widgets are another easy-to-miss frontend-specific component.

A widget may execute only on the forum index, sidebar, member page or another public location.

It may perform:

Database queries
Add-on callbacks
External API requests
Custom template rendering

If only pages containing one widget fail, temporarily disable or remove that widget from the affected position.

Then test again.

If the page works, determine whether the widget itself or the add-on that provides it is responsible.

Diagnosis Path H: Friendly URLs or Rewrite Rules Are Broken

Not every frontend failure is a PHP exception.

Sometimes the forum index loads while rewritten public URLs fail.

For example:

/forums/example.5/
/threads/example-thread.123/

may return errors while direct script-based routing behaves differently.

This suggests investigation of:

Apache rewrite rules
Nginx routing configuration
Friendly URL configuration
Reverse-proxy rules
Recent server migrations

Ask what changed

Was the forum moved to another server?
Was Apache replaced with Nginx?
Was a CDN or reverse proxy added?
Were rewrite rules edited?
Was the forum moved into or out of a subdirectory?

If the Admin Control Panel uses a route that still works while friendly frontend routes do not, the routing layer becomes far more suspicious than the database.

PRBLEM Diagnosis: If some URLs fail while others reach XenForo normally, distinguish a routing failure from an application failure before changing PHP code.

Diagnosis Path I: Frontend Cache Is Serving a Broken Response

A reverse proxy, CDN or server cache may cache public pages while deliberately bypassing the Admin Control Panel.

This can produce exactly this pattern:

Admin Control Panel → Works
Public forum → Error

because the ACP request reaches XenForo directly while the public request passes through another cache layer.

Potential layers include:

Cloudflare
Varnish
Nginx cache
LiteSpeed
Hosting-provider page cache
Other reverse proxies

Controlled test

If the error began after a temporary frontend failure and the application now appears healthy, purge only the affected public URL or relevant cache layer.

Then test again in a private browser window.

If the error disappears only after a CDN or reverse-proxy purge, the old error page itself may have been cached.

Do not make cache purging your first response when XenForo’s own server error log contains a new PHP exception.

Diagnosis Path J: An External Service Fails Only on Frontend Requests

A frontend add-on may contact an external service when rendering public pages.

Examples include:

Advertising APIs
Social APIs
Image services
Spam or reputation services
Statistics systems
Remote content providers

If the remote service becomes unavailable and the add-on does not handle the failure correctly, the public request can fail while the ACP remains healthy.

Clues

The problem is intermittent.
The error log references HTTP, cURL, DNS or connection failures.
Disabling one integration restores the frontend.
Database and PHP resources appear healthy.

Do not increase PHP memory or rebuild templates for a remote API timeout.

Fix the correct layer.

Diagnosis Path K: Check XenForo File Integrity

If the error began after an upgrade, manual upload or server migration, check file integrity.

XenForo provides a file health check.

If the Admin Control Panel is available, use its file health-check functionality.

If you have SSH access, run from the XenForo installation directory:

php cmd.php xf:file-check

To check XenForo core specifically:

php cmd.php xf:file-check XF

You can also specify an add-on ID to check files belonging to a supported add-on.

This can identify:

Missing files
Unexpectedly modified files
Incomplete uploads
Potential deployment problems

If the error log references a XenForo core file that fails the integrity check, repair the file set using the correct XenForo package rather than manually rewriting core code.

Diagnosis Path L: Enable XenForo Debug Mode for Deeper Investigation

If the normal error log is not enough, XenForo debug mode can expose additional request information.

Open:

src/config.php

Temporarily add:

$config['debug'] = true;

Debug mode can provide details such as:

Page processing time
Database query count
Memory usage
Controller and action information
Template information
Detailed query traces

This can be particularly useful when the frontend does not completely crash but one route behaves incorrectly or becomes extremely slow.

Do not leave debug mode enabled unnecessarily on a production forum.

Special Case: Forum Works with the Default Style but Not Your Custom Style

This is one of the strongest style-related diagnostic results you can obtain.

Default / clean style → Works

Custom style → Error

Do not continue testing PHP workers or database performance.

Concentrate on:

Customized templates
Outdated templates
Style-specific template modifications
Macros
Custom JavaScript
Custom style add-ons

If the problem began after a specific template edit, revert that edit first.

Special Case: Only One Thread Produces the Error

If thousands of threads work and one specific thread fails, a global XenForo installation problem is unlikely.

Investigate content unique to that thread:

A specific attachment
A particular embedded media item
An unusual post value
A deleted or malformed entity referenced by an add-on
A custom BB code
An add-on field

Check the Server error log immediately after opening that thread.

The request URL in the error entry can confirm that the logged exception belongs to the affected thread.

PRBLEM Diagnosis: One broken piece of content should lead to content-specific investigation, not a complete XenForo reinstall.

Special Case: Forum Index Works but Threads Return an Error

This pattern reduces the suspect list significantly.

Look for functionality specific to thread viewing:

Thread controller extensions
Post macros
Reaction add-ons
Postbit modifications
Attachment rendering
Custom thread fields
Thread-specific widgets

Disable components from this group first rather than unrelated admin or registration add-ons.

Special Case: Guests Get an Error but Administrators Do Not

This may appear especially confusing because administrators can browse the public forum normally.

Use a private browser window where you are not logged in.

If the guest view fails consistently, investigate:

Guest permissions
Guest advertising
Guest-only widgets
Consent systems
Page cache applied only to anonymous traffic
Add-ons with guest-specific code paths

This also helps distinguish a normal XenForo response from a broken cached guest response.

Special Case: Error Started Immediately After Installing an Add-on

The timeline gives you a high-value suspect.

Forum works
        ↓
Add-on installed
        ↓
Frontend error begins
        ↓
ACP still works

Disable the new add-on from the Admin Control Panel.

Test again.

If the forum works, check:

Whether the add-on supports your XenForo version
Whether it requires another add-on
Whether all files were uploaded correctly
Whether its installation completed
Whether the Server error log identifies its code

Do not immediately uninstall it if you still need to preserve its data for diagnosis.

Special Case: Error Started After a XenForo Upgrade

Do not assume XenForo core is automatically at fault.

An upgrade can expose compatibility problems in:

Old add-ons
Outdated style templates
Template modifications
Custom PHP extensions

Use this order:

Check the Server error log.
Run the file health check.
Disable third-party add-ons.
Test with a clean style.
Review outdated templates.
Re-enable components gradually.

If XenForo works with third-party components removed, the core upgrade may simply have revealed an incompatibility.

Three Main Solution Paths

Solution Path 1: Add-on Failure

Use this when disabling an add-on restores the public forum.

Keep the add-on disabled.
Save the relevant Server error log entry.
Check its XenForo version compatibility.
Check required dependencies.
Run its file health check if supported.
Update the add-on if a compatible release exists.
Reproduce the issue on staging.
Send the stack trace to the developer if necessary.

Solution Path 2: Style or Template Failure

Use this when a clean style works but the normal style fails.

Preserve a backup of the custom style.
Identify recently edited templates.
Check outdated template warnings after upgrades.
Disable style-related add-ons or template modifications.
Revert one change at a time.
Test the exact failing page after every change.

Solution Path 3: Server, Route or Cache Failure

Use this when XenForo’s PHP logs do not identify an application exception.

Determine whether only friendly URLs fail.
Check Apache/Nginx rewrite configuration.
Check recent reverse-proxy or CDN changes.
Purge an affected frontend URL if an error response may be cached.
Check the web-server error log.
Check filesystem permissions when logs indicate access problems.
Run XenForo’s file integrity check.

The Fastest Diagnostic Flow

ACP works, public forum fails
        ↓
Open several public routes
        ↓
All frontend pages fail?
        ↓
YES → global frontend component
NO  → route/content-specific component
        ↓
Open XenForo Server error log
        ↓
New error recorded?
        ↓
YES
        ↓
Does stack trace identify add-on?
        ↓
YES → Disable add-on and retest
NO
        ↓
Test clean/default style
        ↓
Forum works?
YES → Style/template problem
NO
        ↓
Temporarily test:
enableListeners = false
        ↓
Works?
YES → Listener/add-on layer
NO
        ↓
Temporarily test:
enableTemplateModificationCallbacks = false
        ↓
Works?
YES → Template callback layer
NO
        ↓
Run XenForo file check
        ↓
Check routing / rewrite rules
        ↓
Check CDN / reverse proxy
        ↓
Check server error logs
        ↓
Investigate route-specific content or external service

Do Not Do These Things

Do not reinstall XenForo because the public frontend fails while ACP works.
Do not uninstall every add-on.
Do not delete large XenForo tables.
Do not overwrite a custom style without backing it up.
Do not leave enableListeners disabled as a permanent fix.
Do not leave template-modification callbacks disabled permanently without finding the responsible component.
Do not enable development mode simply as a generic troubleshooting step.
Do not clear every cache before checking the Server error log.
Do not rewrite web-server configuration when the log already identifies a PHP exception.
Do not blame XenForo core merely because a problem appeared after an upgrade.
Do not modify XenForo core files to work around a third-party add-on error.

How to Verify the Fix

Do not consider the issue solved after opening the forum homepage once.

Test several routes and user states.

Open the forum index.
Open multiple forums.
Open several threads.
Open a member profile.
Test as a guest.
Test as a logged-in member.
Test the normal custom style.
Post or preview a reply if appropriate.
Check the Server error log again.
Confirm no new matching error is generated.

If you used temporary configuration changes such as:

$config['enableListeners'] = false;

or:

$config['enableTemplateModificationCallbacks'] = false;

remove those diagnostic overrides and test again under the normal XenForo configuration.

A solution that works only because all add-on functionality remains disabled is not a finished repair.

If the Forum Still Fails

At this stage, create a diagnostic record before making additional changes.

Record:

XenForo version
PHP version
Exact failing URL
Exact visible error
Whether the Admin Control Panel works
Whether all frontend routes fail
Whether guests and members behave differently
Whether a clean style works
Whether disabling add-ons changes the result
Whether disabling listeners changes the result
Whether disabling template-modification callbacks changes the result
The newest Server error log entry
The full stack trace
The result of the file health check
Recent add-on, style, XenForo or server changes

Compare these two support requests:

My XenForo forum is broken but admin works.

and:

The Admin Control Panel works normally, but every public route produces an error. The Server error log records the same exception on each request and the stack trace points to Vendor/AddOn. Disabling that add-on restores the frontend immediately. The file health check for XenForo core passes.

The second report has already isolated the problem to a very small part of the system.

Quick Recovery Checklist

Confirm the Admin Control Panel works consistently.
Test multiple public XenForo routes.
Compare guest and logged-in behaviour.
Check XenForo’s Server error log immediately after reproducing the error.
Save the stack trace before clearing anything.
Identify third-party add-on paths in the error.
Disable suspected add-ons rather than uninstalling them.
Test with a clean or minimally modified style.
Review recent template changes.
Temporarily test listener disabling when appropriate.
Temporarily test template-modification callback disabling when appropriate.
Check widgets on affected pages.
Check friendly URL and rewrite configuration if route behaviour differs.
Check reverse-proxy and CDN caching.
Investigate external services when logs show connection failures.
Run XenForo’s file health check.
Use debug mode only when deeper request information is required.
Change one variable at a time.
Remove temporary diagnostic config overrides when finished.
Retest multiple frontend pages and check for new error-log entries.

Final Diagnosis

A working XenForo Admin Control Panel combined with a broken public forum is not contradictory.

It tells you that large parts of XenForo are still functioning.

The task is to identify what the public request uses that the administrative request does not.

Add-on layer: A frontend listener, controller extension or entity extension fails.

Template layer: A modified template or macro fails during public rendering.

Template modification layer: An add-on modification or PHP callback breaks frontend output.

Style layer: The customized public style is broken while XenForo’s administrative interface remains unaffected.

Route layer: Friendly URL or web-server routing rules prevent requests from reaching XenForo correctly.

Cache layer: A CDN or reverse proxy continues serving a broken frontend response while bypassing the ACP.

File layer: Missing or altered XenForo or add-on files break only the code path used by the public application.

External-service layer: A public integration fails while administration remains independent of it.

The fact that the Admin Control Panel works is therefore not just good news.

It is one of your strongest diagnostic clues.

PRBLEM Principle: When XenForo administration works but the forum does not, compare the two execution paths. The component present only in the failing path is where the investigation should become narrower.

Did this solution fix your problem?

Optional feedback helps us improve this guide. Never send private data.

PRBLEM / COMMUNITY

Discuss This Solution

Ask a question, compare results, or share a safe fix that worked for you.

Describe the exact issueInclude the error, device or software version, and what you already tried.

Protect your informationNever post passwords, recovery codes, private logs or personal data.