> ## 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.
# Query Parsing Errors
> Resolve Lucene query parsing failures that prevent Nextedy RISKSHEET from loading work items, cause errors in filter definitions, or block access to LiveDoc documents after Polarion upgrades.
export const LastReviewed = ({date}) => {
if (!date) return null;
const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
year: "numeric",
month: "long",
day: "numeric",
timeZone: "UTC"
});
return
Last reviewed on {formatted}
;
};
## Symptoms
Query parsing errors typically manifest as one or more of the following indicators:
| Symptom | Location | Likely Cause |
| ------------------------------------------------- | --------------- | --------------------------------------------------------------------------------- |
| `Error parsing filter definition:` message | Browser console | Malformed filter syntax in comparison or baseline view |
| Unparseable query errors blocking document access | Server logs | Polarion configuration issue (e.g., Auto Assignment with invalid inputs) |
| `Entity not found` error when loading data | Server logs | Missing or inaccessible work item reference in query results |
| Blank grid or missing risk items | Risksheet UI | Query construction failure in sheet configuration data type configuration |
| Autocomplete search returns no results | Link editor | Invalid `queryFactory` function, search input too short, or incorrect type filter |
| Stack traces mentioning Nextedy components | Server logs | Data service interceptor appearing in unrelated Polarion exceptions |
## Diagnose the Error Source
Query parsing errors in Risksheet can originate from two distinct sources: the Risksheet configuration itself, or from Polarion platform features that interact with the same data layer. Before modifying any Risksheet configuration, determine where the error originates by following this diagnostic flow:
After upgrading Polarion to version 2410 or later, you may see Nextedy components (such as data service hooks) in stack traces for errors that originate entirely within Polarion. These hooks act as data service interceptors and appear in the call stack for **any** data service exception, even when Risksheet is not the cause. Always examine the actual error message and the originating query text, not the stack trace class names, to determine the true source of the problem.
After Polarion version upgrades, query parsing errors are frequently caused by Polarion features (such as Auto Assignment) with invalid inputs, not by Risksheet. Investigate Polarion's own configuration settings before modifying sheet configuration or Risksheet project properties.
## Fix 1: Post-Upgrade Query Errors from Polarion
If query parsing errors appeared immediately after a Polarion upgrade, the root cause is most likely a Polarion configuration issue:
1. **Check Auto Assignment rules** -- Navigate to **Administration > Work Items > Auto Assignment** in the affected project. Verify that all rules contain valid field references and user assignments. Invalid entries in Auto Assignment are a known source of unparseable query errors after upgrading to Polarion 2310 and 2410.
2. **Review workflow script queries** -- Open the workflow configuration for each work item type used in Risksheet. Check that any Lucene queries embedded in workflow conditions or scripts use syntax compatible with the new Polarion version.
3. **Verify custom field expressions** -- If you use custom field default values or expressions that contain Lucene query fragments, confirm they do not contain unescaped special characters.
4. **Check document ID format changes** -- Polarion upgrades may change how document IDs with the `_default/` prefix are handled. Risksheet automatically strips the `_default/` prefix from document IDs when constructing queries, but if the upgrade changed the ID format, verify the documents are still accessible.
| Polarion Version | Known Query Issue | Risksheet Fix |
| ---------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 2310 | `UnsupportedOperationException` for `renderingLayouts` document field rendering | No functional impact; update Risksheet to 24.7.0+ to suppress the log error |
| 2410 | Unparseable query errors from Auto Assignment feature | Fix Auto Assignment configuration in Polarion; not a Risksheet issue |
## Fix 2: Work Item Type Configuration Errors
Risksheet uses Lucene queries to load work items based on the `dataTypes` configuration in sheet configuration. The `types` property determines which Polarion work item types appear in the grid. Multiple types are combined with OR logic in the generated query.
Verify your data type configuration:
```yaml theme={null}
dataTypes:
risk:
types:
- fmea_risk
role: has_cause
query: ''
task:
types:
- mitigation_action
role: mitigates
showInMenu: true
query: ''
```
| Property | Purpose | Common Error |
| ------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `types` | Work item type ID(s) to include | Misspelled type name; **at least one type is required** or the system throws an error |
| `role` | Link role for creating relationships | Invalid or nonexistent role ID in Polarion |
| `query` | Custom Lucene query fragment appended to auto-generated filters | Malformed Lucene syntax |
| `showInMenu` | Whether creation options appear in context menu (default: `true`) | N/A |
The `types` property must contain at least one valid Polarion work item type ID. An empty or missing `types` array causes a query construction error that prevents the grid from loading any items.
## Fix 3: Custom Query Syntax Errors
The `query` property under `dataTypes.risk` or `dataTypes.task` accepts Lucene query fragments. These fragments are dynamically expanded with project and document context, then combined with the auto-generated type filters using AND logic.
**Rules for custom queries:**
* Empty or whitespace-only queries are safely ignored by the system
* Document IDs with `_default/` prefix have the prefix stripped automatically before query construction
* Document IDs are quoted automatically to handle spaces and special characters
* Multiple query conditions are merged with AND logic; empty conditions are skipped
**Lucene special characters that must be escaped:**
| Character | Must Escape | Notes |
| --------------- | ----------------- | -------------------------------------------------- |
| `+` `-` | Yes | Escape at start of terms |
| `&&` `\|\|` | Yes | Boolean operators |
| `!` | Yes | NOT operator |
| `(` `)` | Yes | Grouping operators |
| `{` `}` `[` `]` | Yes | Range operators |
| `^` `"` `~` | Yes | Boost, phrase, fuzzy operators |
| `*` `?` | Context-dependent | Wildcard operators; escape only if literal |
| `:` `\` `/` | Yes | Field separator, escape character, regex delimiter |
**Troubleshooting steps for custom queries:**
1. Remove the custom `query` value temporarily to confirm the base auto-generated query works
2. Test your Lucene query directly in Polarion's work item search interface to verify syntax
3. Add query fragments back incrementally to isolate the failing clause
4. Check that all field names referenced in the query exist in the target work item type
```yaml theme={null}
dataTypes:
risk:
types:
- fmea_risk
query: NOT status:rejected AND NOT status:obsolete
```
If you cannot resolve a custom query error quickly, set the `query` property to an empty string `""`. The system ignores empty queries and uses only the automatic project, document, and type scope filters. This restores grid loading while you debug the query offline.
## Fix 4: Query Factory Function Errors
If you use `queryFactory` functions to dynamically filter which items are available for linking in item link or multi-item link columns, the function must return a valid Lucene query string. Common mistakes in query factory functions include:
* Returning `undefined` or `null` instead of an empty string
* Missing quotes around string values in the returned query
* Referencing a field name that does not exist on the target work item type
* Using JavaScript template literals with unescaped Lucene special characters
Verify the function syntax in your sheet configuration:
```yaml theme={null}
dataTypes:
task:
queryFactory: function(item) { return 'type:mitigation_action AND NOT status:closed';
}
```
The `queryFactory` function receives the current row's work item data as its parameter. Use it to construct context-aware queries, such as filtering linked items by the same project or status.
## Fix 5: Search and Autocomplete Failures
If the autocomplete editor in link columns fails to return results, verify the following:
1. **Minimum search length** -- The autocomplete editor for multi-item link columns requires a minimum of **3 characters** before executing a search query. Typing fewer characters produces no results by design.
2. **Query factory configuration** -- If the column uses a custom `queryFactory`, verify the function returns a valid query for the current item context.
3. **Type filtering** -- The autocomplete search filters results by the configured work item type and optionally by a custom query. Confirm the target work item type exists and has items within the search scope.
4. **Duplicate prevention** -- The autocomplete editor enforces uniqueness. You cannot select an item that is already linked. If you attempt to add a duplicate, a toast notification informs you and the selection is rejected.
If the autocomplete returns no matches, users can create new work items directly from the link editor when the column's `canCreate` property is set to `true` (the default for `itemLink` and `multiItemLink` columns). This reduces context switching when the desired target item does not yet exist.
## Fix 6: Filter Definition Parse Errors
If you see `Error parsing filter definition:` in the browser developer console during baseline comparison or filter operations:
1. Open the browser developer console (`F12`) and locate the exact error message
2. Identify the specific filter definition string that failed to parse
3. Check your sheet configuration for any custom filter or comparison configurations
4. Verify the filter uses valid Lucene query syntax with properly escaped special characters
5. If the error occurs only during baseline comparison, check that both the current and baseline revisions use compatible query formats
## Verification
After applying the appropriate fix, verify the resolution:
1. Clear your browser cache and reload the Risksheet document
2. Open the browser developer console (`F12`) and check the Console tab for any remaining `Error parsing filter definition:` messages
3. Check the Network tab to confirm the `/api/config` endpoint returns a successful response
4. Verify the Risksheet grid loads completely with all expected risk items displayed
5. Test autocomplete search in link columns by typing 3 or more characters
6. If you modified server-side Polarion configuration (Auto Assignment, workflows), restart the Polarion server and verify the server logs are free of query parsing exceptions
You should now see the Risksheet grid fully populated with all expected risk items, filter operations working without console errors, and autocomplete search returning matching results when typing 3 or more characters.
## See Also
* [Rendering and Display Errors](/risksheet/troubleshooting/rendering-errors) -- resolve grid display problems after data loads successfully
* [Slow Page Loading](/risksheet/troubleshooting/performance-slow-loading) -- fix performance issues related to complex queries
* [Cell Editing Issues](/risksheet/troubleshooting/cell-editing-issues) -- troubleshoot editing problems after query fixes
* [Save Operation Failures](/risksheet/troubleshooting/save-failures) -- resolve save errors related to data queries
* [Error Messages Reference](/risksheet/troubleshooting/error-messages) -- complete list of Risksheet error messages and their meanings