Script Errors - Nextedy Documentation

When Planningboard encounters a configuration or script error, it signals this through an error indicator in the board UI. The way errors are surfaced depends on who is viewing the board: widget editors see detailed error messages, while regular users see a generic warning. This guide walks you through identifying, reading, and resolving the most common error conditions.

How Planningboard Signals Errors

Planningboard uses an error indicator built into the board toolbar. The indicator reflects the current state of the widget configuration and any scripts it evaluates at render time.

+--------------------------------------------------------------+
|  Board Toolbar                                               |
|                                                              |
|  [Planningboard Title]              [ ⚠ Configuration Error ]|
+--------------------------------------------------------------+
         |
         | Editor view
         v
  Detailed error message with property name, script
  excerpt, and line reference
         |
         | Non-editor (user) view
         v
  Generic warning only — no internal detail exposed

Editor view — if you have edit permissions on the widget, the error indicator shows the full detail: which property failed, what the script evaluated to, and where.
User view — users without edit access see a generic warning indicator. They cannot proceed until an editor resolves the issue.

The board may still render partially even when an error is present. The error indicator shows that at least one configuration or script evaluation failed — it does not necessarily mean the whole board is blank.

Open the Error Detail

On the Planningboard page, look for the warning indicator in the toolbar (top-right area of the board).
If you have widget-editor access, click the indicator to expand the error detail panel.
Read the full error message. Note:
- The property name involved (e.g., a widget parameter like plansQuery, a swimlane assignment expression, or a script field).
- The error type (syntax error, null reference, unresolved variable, etc.).
- The script excerpt or value that triggered the error, if shown.

If you do not see a detailed error (only the generic warning icon), check that you are logged in with a role that has edit access to the LiveDoc or Wiki page containing the widget.

Locate the Failing Configuration

Open the widget’s configuration panel (Edit > Widget Parameters in the Polarion page editor). Cross-reference the property name from the error detail with the corresponding widget parameter.Common parameters that drive script evaluation:

Parameter type	What it does	Error-prone when…
Plan query (`plansQuery`)	Lucene query selecting Plans onto the board	Query syntax is invalid or references a non-existent field
Swimlane assignment expression	Determines how work items map to swimlanes	Enum field ID is wrong, or field type is unsupported
Card content template	Velocity/script template for card body	Template references an undefined variable
Capacity configuration	Expressions used for capacity calculation	Whitespace-sensitive values contain extra spaces
Page parameters	Dynamic values injected from URL/page	Page parameter name does not match the declaration

See Widget Parameters Overview for a full parameter reference.

Fix Common Error Patterns

Plan query syntax error

Symptom: Board shows no columns (Plans), error mentions plansQuery or a Lucene parse failure.Fix: Open the widget configuration and correct the plansQuery value. Lucene queries are case-sensitive for field names. Example of a valid query:

plansQuery=template.id:iteration AND NOT status:closed

Check that:

Field names exactly match Polarion field IDs (e.g., type.id, not typeId).
String values are unquoted when they contain no spaces, or double-quoted when they do.
Boolean operators (AND, OR, NOT) are uppercase.

Enum swimlane field not supported

Symptom: Swimlanes do not render, error references the resource field or assignment mode.Fix: Planningboard’s ENUM assignment mode supports IEnumType fields and IListType fields whose items are IEnumType. The following field types are not supported as swimlane assignment fields: status, resolution, and type. Switch to a custom enum field or choose a different assignment mode.

Using status, resolution, or type as the swimlane resource field is a known unsupported configuration. The board will show an error rather than silently grouping incorrectly. Replace the resource field with a supported custom enum field.

Capacity configuration whitespace

Symptom: Capacity bar values appear zero or incorrect, or an error references capacity parsing.Fix: Capacity configuration parameters are whitespace-sensitive. Remove leading or trailing spaces from all capacity-related widget parameter values:

# Correct — no surrounding spaces
capacity=8

# Incorrect — trailing space causes parse failure
capacity=8 

Whitespace around capacity parameter values is a known source of silent misconfiguration. Even a single trailing space can cause the capacity bar to show zero or trigger an error. Always verify there are no extra spaces when setting capacity parameters.

Velocity template / card content error

Symptom: Cards render blank or show a raw error string; error mentions a template property or variable.Fix: Card content templates use Velocity syntax. Common causes:

Referencing a custom field using $workItem.customFields.myField — this form does not return the value. Use $workItem.getValue("myField") instead.
Referencing an enum-typed field without calling .getName() — the raw EnumOption[...] object is printed instead of the label.
An undefined variable reference ($myVar) with no fallback — Velocity prints the literal $myVar string when the variable is null.

Example of a correctly written card template snippet:

$workItem.getValue("severity").getName()

Page parameter not resolved

Symptom: Board ignores URL-driven filters or shows an error about an unresolved parameter.Fix: The page parameter name in the widget configuration must exactly match the parameter name declared in the page header or URL. Names are case-sensitive. See Use Page Parameters and Dynamic Filtering with Page Parameters for the declaration syntax.

Refresh the Board After Fixing

After correcting a widget parameter, save the widget configuration, then use the board’s Refresh control (or reload the page) to force the board to re-fetch all data from the server. A refresh reloads all Plans and work items and resets the board state.

The board persists swimlane collapse state and scroll position in browser localStorage. If the board looks different after a fix than expected, try clearing localStorage for the page (browser DevTools > Application > Local Storage > clear the relevant keys) or open the board in a private/incognito window to rule out stale state.

Diagnose Infinite Loading or Blank Board

If the board never finishes loading (infinite spinner) and no error indicator appears, the issue may not be a script error:

                    Board Load Attempt
                           |
          +----------------+----------------+
          |                                 |
    Script / Config Error              Network / Firewall Issue
          |                                 |
  Error indicator appears          Infinite spinner, no error
  in board toolbar                  indicator, DevTools shows
                                   blocked or timed-out requests

Open the browser developer tools (F12) and check the Network tab for failed or blocked requests to the Polarion server.
If requests are being blocked by a firewall or proxy, this is a network-layer issue — not a Planningboard script error. Refer to Network and Firewall Requirements for the list of required endpoints.
If requests reach the server but return error responses (HTTP 4xx/5xx), check the Polarion server logs and verify the widget configuration is valid.

Infinite loading that is never accompanied by a script error indicator is frequently caused by an internal firewall or proxy blocking requests to the Polarion server — not by a misconfigured widget. Diagnose network connectivity first before troubleshooting widget parameters.

Verification

After applying your fix:

Save the widget configuration.
Reload the Planningboard page.
You should now see the board render without the warning indicator in the toolbar, Plans appear as columns, and work item cards distributed across swimlanes as expected.

If the error indicator persists, repeat Step 1 to read the updated error detail — the message may have changed to reflect a new underlying issue now that the previous one is resolved.

​How Planningboard Signals Errors

​Plan query syntax error

​Enum swimlane field not supported

​Capacity configuration whitespace

​Velocity template / card content error

​Page parameter not resolved

​Verification

​See Also

How Planningboard Signals Errors

Plan query syntax error

Enum swimlane field not supported

Capacity configuration whitespace

Velocity template / card content error

Page parameter not resolved

Verification

See Also