Liquid error messages and tracing

Liquid is the server-side templating language used in Power Pages (formerly Power Apps Portals) to render dynamic content. As powerful as it is, misused or misconfigured Liquid code can lead to cryptic Liquid error messages like:

• Liquid error: Exception has been thrown by the target of an invocation.
• Liquid error: Object reference not set to an instance of an object.
• Liquid error: 'xxxx' is not a valid object.
• Liquid error: unexpected end of file.

This guide walks you through how to detect, decode, and trace Liquid errors and optimize your portal code for stability and performance.

---

1. Understanding Liquid Error Types

Liquid errors fall into three primary categories:

Type	Description
Syntax Errors	Mistakes in tags, filters, or variable expressions
Null/Empty Reference	Attempting to access properties on null or empty objects
Runtime Exceptions	Unhandled errors during execution (e.g., dividing by zero)

---

2. Enable Detailed Error Logging (Dev Only)

By default, Power Pages suppresses full error details for security. To troubleshoot:

Step:

1. Navigate to Portal Management App.
2. Go to Site Settings.
3. Add or modify the following settings:

Name	Value
EnableCustomErrors	false
ShowExceptionDetailsOnErrorPage	true

Note: Only enable this in development or test environments. Disable before going live.

---

3. Common Liquid Error Scenarios & Fixes

A. Null Object Reference

Error: Liquid error: Object reference not set...

Cause: Accessing a property from a null object.

Example:

{{ user.fullname }}

If user is null, this fails.

Fix:

{% if user %}
  {{ user.fullname }}
{% endif %}

---

B. Invalid Filters or Syntax

Error: Liquid error: Filter 'abc' not found.

Cause: Typo in a filter or using an unsupported one.

Fix: Use valid filters like size, date, where, sort, truncate.

Wrong:

{{ collection | wrongfilter }}

Correct:

{{ collection | size }}

---

C. Malformed For Loop

Error: Liquid error: unexpected end of file.

Cause: Unclosed for or if block.

Fix:

{% for item in items %}
  {{ item.name }}
{% endfor %}

---

D. Undefined Variables

Error: Liquid error: 'xyz' is not a valid object.

Fix: Use assign or check if data is available.

{% assign xyz = entities.account | first %}
{% if xyz %}
  {{ xyz.name }}
{% endif %}

---

4. Use Try-Catch Style Liquid Blocks

Liquid doesn’t have native try-catch, but you can emulate graceful handling using conditional checks.

Pattern:

{% if entity and entity.name %}
  {{ entity.name }}
{% else %}
  <p>Name not available</p>
{% endif %}

---

5. Trace Using trace and comment Blocks

To debug Liquid logic, use comment or trace:

{% comment %} Checking account entity {% endcomment %}

For test output (in dev only):

{{ "Inside the account check block" }}

You can also use:

{{ myObject | json }}

This helps visualize what is inside an object.

---

6. Using Browser Tools to Identify Liquid Errors

Although Liquid runs server-side, you can detect errors by inspecting:

• HTML Output: Search for Liquid error: in rendered page source.
• DevTools > Network Tab: Look at the response HTML for AJAX calls containing templates.

---

7. Best Practices for Liquid Debugging

• Use {% capture %} to store and test outputs.
• Modularize code via Web Templates and Includes.
• Wrap all dynamic calls with checks: {% if entity %}, {% if list.size > 0 %}, etc.
• Always validate data structure before accessing properties.

---

8. Sample Debugging Workflow

Example: You’re rendering a logged-in user’s account name.

{% assign account = user.parentcustomerid %}
{{ account.name }}

Fix:

{% if user.parentcustomerid %}
  {% assign account = user.parentcustomerid %}
  {{ account.name }}
{% else %}
  <p>No account linked</p>
{% endif %}

---

9. Testing in Isolation

Use a blank Web Template or Ad-Hoc Web Page to test new Liquid code:

1. Create a temporary Web Template.
2. Test Liquid code with mock data or known entity values.
3. Remove the template or isolate logic using {% comment %} blocks when not needed.

---

10. Preventing Errors in Production

Once resolved:

• Set EnableCustomErrors = true.
• Use preview mode for changes in a staging environment.
• Audit changes through source control or deployment pipelines using ALM practices.