> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Script Errors

> Diagnose and fix configuration or script errors that prevent your Nextedy PLANNINGBOARD from loading or displaying data correctly.

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.

```text theme={null}
+--------------------------------------------------------------+
|  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.

<Note>
  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.
</Note>

<Steps>
  <Step title="Open the Error Detail">
    1. On the Planningboard page, look for the warning indicator in the toolbar (top-right area of the board).
    2. If you have widget-editor access, click the indicator to expand the error detail panel.
    3. 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.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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](/planningboard/guides/configuration/widget-parameters) for a full parameter reference.
  </Step>

  <Step title="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:

    ```properties theme={null}
    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.

    <Warning>
      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.
    </Warning>

    ### 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:

    ```properties theme={null}
    # Correct — no surrounding spaces
    capacity=8

    # Incorrect — trailing space causes parse failure
    capacity=8 
    ```

    <Warning>
      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.
    </Warning>

    ### 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:

    ```javascript theme={null}
    $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](/planningboard/guides/configuration/page-parameters) and [Dynamic Filtering with Page Parameters](/planningboard/guides/advanced/dynamic-filtering) for the declaration syntax.
  </Step>

  <Step title="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.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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:

    ```text theme={null}
                        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](/planningboard/guides/troubleshooting/network-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.

    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

## Verification

After applying your fix:

1. Save the widget configuration.
2. Reload the Planningboard page.
3. 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.

## See Also

* [Widget Parameters Overview](/planningboard/guides/configuration/widget-parameters) — full reference for all widget parameters
* [Config Scripts](/planningboard/guides/advanced/config-scripts) — authoring configuration scripts
* [Item Scripts](/planningboard/guides/advanced/item-scripts) — authoring per-item scripts
* [Dynamic Filtering with Page Parameters](/planningboard/guides/advanced/dynamic-filtering) — page parameter syntax and usage
* [Network and Firewall Requirements](/planningboard/guides/troubleshooting/network-requirements) — required endpoints and proxy configuration
* [Common Errors](/planningboard/guides/troubleshooting/common-errors) — broader Planningboard error reference

<Accordion title="Sources">
  **KB Articles**

  * Troubleshooting Script Errors in Planningboard

  **Support Tickets**

  * [#6659](https://support.nextedy.com/helpdesk/tickets/6659)

  **Source Code**

  * `commons.js`
  * `PlanningBoardWidgetDependenciesProcessor.java`
  * `PlanningBoardWidgetRenderer.java`
</Accordion>