Diagnosing Empty PageReference Fields in ProcessWire

Recognizable Condition

When rendering a page, a PageReference field (e.g., $page->related_items) returns an empty PageArray even though you expect one or more related pages to be present. The field may appear blank in the frontend, or debugging output shows 0 items.

Causes & Quick Diagnosis

Possible Cause	What to Look For
Field not assigned to the template	Editing the page shows the field, but the template used for rendering does not include it.
Referenced pages unpublished, hidden, or access‑restricted	The target pages have status unpublished, are hidden, or require a role the current user lacks.
Output formatting disabled (unformatted access)	Code uses $page->getUnformatted('field') or similar, returning raw value which may be null.
Multilingual language visibility hides references	Site uses multiple languages; referenced pages are not published in the active language.
Hook or custom modifier alters the field value	A hook on Page::get, FieldtypePagevalue::loadPage, or similar returns an empty PageArray.

Ordered Checks

1. Verify template field assignment

   In the admin, go to Setup → Templates → [your‑template] → Fields. Ensure the PageReference field is listed. If missing, add it and save.

   Where to run: Admin UI. Permissions: Superuser or template manager.

2. Check status and access of referenced pages

   Open the page that should be referenced. Confirm its status is published (not hidden or trashed). Then, while logged in as the user experiencing the issue, verify you can view the page directly. If not, adjust access roles or publish the page.

   Where to run: Admin UI > Pages. Permissions: Page editor.

3. Confirm you are using formatted access

   In your template code, replace any $page->getUnformatted('fieldname') calls with $page->fieldname. Formatted access automatically loads the related PageArray.

   Where to run: Template file (e.g., /site/templates/your-template.php).

4. Check multilingual language settings

   If the site uses Languages, edit each referenced page and ensure it has a version for the current language (or enable language fallback). Publish the language version if missing.

   Where to run: Admin UI > Languages > Edit language version of each referenced page.

5. Temporarily disable hooks

   Add the following line to /site/config.php to bypass all hooks for testing:

   $config->disableHooks = true;

   Reload the page. If the field now returns pages, a hook is the culprit. Remove the line after testing and isolate the offending hook by disabling them one‑by‑one in /site/init.php or module files.

   Where to run: /site/config.php. Permissions: File system access.

Fixes Tied to Findings

• Template assignment – Add the field to the template via Admin → Setup → Templates → Fields.
• Page status/access – Publish the referenced pages, adjust their hidden status, or grant the needed role (e.g., via Access → Roles).
• Output formatting – Use formatted access ($page->fieldname) or ensure $config->debug is not suppressing output formatting.
• Multilingual visibility – Publish language versions or enable language fallback in Setup → Languages.
• Hook interference – Locate the hook (search for addHookAfter('Page::get', ...) or similar) and modify it to return the original value, or disable it if unnecessary.

Escalation Criteria

If after performing all five checks the PageReference field remains empty:

1. Enable ProcessWire’s debug mode ($config->debug = true;) and examine the error log for any PHP warnings or exceptions.
2. Check for custom modules that override FieldtypePagevalue or PageArray behavior.
3. Consider reproducing the issue on a clean dev install with the same template and field configuration to rule out database corruption.
4. If the problem persists, gather the field’s settings (screenshot of Inputfield PageReference configuration) and the template code, then post to the ProcessWire forums or GitHub issues with those details.

---

Practical verification: After each fix, reload the page and output count($page->fieldname) or $page->fieldname->first()->title to confirm a non‑empty result.