Diagnosing 404, 500, and Blank Front-End Pages in ProcessWire

Recognizing the Symptom

When a published page returns 404, ProcessWire cannot resolve a template file for that page. A 500 or blank response indicates a PHP fatal error inside the template or in _init.php.

Cause & Diagnostic Table

Symptom	Typical Cause	Diagnostic Check
404 Page Not Found	Missing, renamed, or misnamed template file; alternate filename mismatch; access-control restriction.	Check $page->template->name and alternate filename; verify the file exists in site/templates.
500 or blank page	Syntax error or exit() in _init.php or template; delayed output misconfigured; cache serving stale output.	Enable $config->debug or run $pages->get('/path/')->render() from a bootstrap script.
Blank page with no error logs	Output buffering started early; header already sent; hidden die() in a hook.	Search for ob_start() or header() calls after buffering starts.

Ordered Checks

1. Verify HTTP Status

   curl -I https://example.com/failing-page
   # Look for HTTP/1.1 404 or 500

2. Confirm Page is Published

   In the admin, open the page and ensure Published is checked and the page is not in the trash.

3. Run as Superuser

   Log in as a user with the admin role and visit the page. If it renders, the issue is an access-control rule.

4. Check Template Resolution

   $template = $page->template;
   echo "Template name: {$template->name}\n";
   echo "Alternate filename: {$template->alternate_filename}\n";
   $path = $config->paths->templates . $template->file;
   echo "Resolved path: {$path}\n";

   Confirm the file exists and matches the name or alternate filename.

5. Inspect _init.php

   cat site/templates/_init.php
   # Look for syntax errors, early exit, or header calls

   Any error here affects every front-end page.

6. Enable Debugging Temporarily

   // In site/config.php
   $config->debug = true;

   Reload the page and examine the error output. Disable debug mode after testing.

7. Check Caching Layers
   • Core cache: $config->cache->enabled and $config->cache->expire.
   • ProCache or other plugins: clear through their UI or via $config->cache->clearAll().

   Clear both caches and retest.

8. Validate Output Buffering

   Search the template for ob_start() and ensure ob_end_flush() is called. Manual echo after buffering starts can trigger header-already-sent warnings.

9. Test with a Scratch Template

   Create a template named test with a file test.php containing only echo "Hello";. Assign it to a fresh page and view it. If the page renders, template resolution works; if not, the problem is in the template engine or access control.

Fixes Tied to Findings

• Missing Template File Restore or rename the file to match $template->name, or set the correct alternate filename in the template editor.
• Syntax Error in _init.php Fix the syntax, remove premature exit(), or comment out the offending line.
• Access-Control 404 Adjust role permissions or remove $page->isAllowed checks that return false.
• Cache Serving Stale Output Disable caching for the template or clear all caches.
• Header Already Sent Move header() calls before any output or buffer the entire page.

Escalation Criteria

If the page still fails after the ordered checks:

• Review server logs (for example, /var/log/apache2/error.log) for PHP fatal errors.
• Confirm file permissions: template files should be readable by the web server user (often www-data).
• Check for conflicting modules or hooks that modify template rendering.
• If the site uses ProCache, verify that the cache directory is writable and not corrupted.

Concrete Example

Suppose /about returns 404. You run:

$page = $pages->get('/about');
echo $page->template->name; // outputs "about"

In site/templates the file about.php is missing, and the template editor shows an alternate filename of about-page.php. Create that file or change the alternate filename to match the existing file. After saving, clear the cache and revisit /about.

Limitations & Safety Notes

• Never leave $config->debug enabled on a live site; it exposes internal paths.
• Changing file permissions to 777 is insecure; match the existing ownership.
• Template cache and ProCache are separate; clearing one does not clear the other.
• The site's own 404 template can fail, causing every not-found response to appear broken; test that template separately.

Practical Result Check

After applying a fix, run:

curl -I https://example.com/failing-page
# Expect HTTP/1.1 200

Optionally, view the rendered page in a browser and confirm the content appears.