ONQL error codes and troubleshooting
ONQL validates queries to identify syntax errors, unsupported attributes, invalid values, and other conditions that may prevent monitoring data from being retrieved. When a query contains an error, the query editor displays an error message and its corresponding code to help you identify the issue.
This document explains the different ONQL error codes, what causes them, and how to resolve them so you can correct your queries and generate reports with the intended monitoring data.
Understanding ONQL error codes
ONQL error codes follow a standard format:
ONQL_ERROR_AREA_NN
Here, AREA identifies the category of error, while NN is a unique number assigned to the error within that category. The error code remains the same even if the corresponding message changes.
For example, ONQL_ERROR_SYNTAX_04 indicates that the sorting direction is missing from a sort clause.
Error code categories
| Category | Error code prefix | Description |
|---|---|---|
| Clause errors | ONQL_ERROR_CLAUSE |
Missing or unsupported query clauses |
| Syntax errors | ONQL_ERROR_SYNTAX |
An incorrect query structure, missing operators, or incomplete expressions |
| Time period and time slice errors | ONQL_ERROR_PERIOD |
Invalid time periods, unsupported intervals, or incorrect custom date ranges |
| Column errors | ONQL_ERROR_COLUMN |
Invalid, duplicate, incomplete, or unsupported report columns |
| Attribute errors | ONQL_ERROR_ATTRIBUTE |
Unsupported attributes, namespaces, aggregations, or operators |
| Value and unit errors | ONQL_ERROR_VALUE |
Invalid values, incompatible data types, or unsupported unit conversions |
| Business rule validation errors | ONQL_ERROR_RULE |
Queries that violate ONQL-specific rules for filtering, aggregation, sorting, or other operations |
Error codes by category
Expand a category to see its error codes, what causes them, and how to resolve them.
Clause errors
Clause errors occur when a required clause is missing or a query uses a clause that is not supported by the selected feature.
| Error code | Error message | Cause and resolution |
|---|---|---|
ONQL_ERROR_CLAUSE_01 |
The clause is not supported for . | The query contains a clause that the selected feature does not support. Remove the unsupported clause. |
ONQL_ERROR_CLAUSE_02 |
The clause is required for . | A mandatory clause is missing. Add the required clause. |
Example: Missing report type
Incorrect
include(monitoring_inventory.monitor_name)
Correct
reporttype="server" | include(monitoring_inventory.monitor_name)
Syntax errors
Syntax errors occur when a query has missing punctuation, incomplete expressions, incorrect separators, or unsupported structures.
| Error code | Error message | How to resolve |
|---|---|---|
ONQL_ERROR_SYNTAX_01 |
Invalid syntax at line , column . Check your query and try again. | Review the query at the specified position and correct the syntax. |
ONQL_ERROR_SYNTAX_02 |
Remove the extra comma before ")". | Remove the extra comma after the last attribute or value. |
ONQL_ERROR_SYNTAX_03 |
The opening parenthesis "(" is not closed. Add the missing closing parenthesis ")". | Close the incomplete function or expression. |
ONQL_ERROR_SYNTAX_04 |
Add asc or desc after the column to specify the sorting order. | Specify asc or desc after the sorting attribute. |
ONQL_ERROR_SYNTAX_05 |
Add | after the reporttype clause. | Add | after the reporttype clause. |
ONQL_ERROR_SYNTAX_06 |
This value must be in double quotes. | Enclose the applicable text value in double quotes. |
ONQL_ERROR_SYNTAX_07 |
Unexpected found at line , column . Replace it with . | Replace the unexpected token with the expected syntax. |
ONQL_ERROR_SYNTAX_08 |
The query is incomplete. Add at line , column . | Complete the expression with the expected token. |
ONQL_ERROR_SYNTAX_09 |
Separate each clause with a space (line , column ). | Add a space between consecutive clauses. |
ONQL_ERROR_SYNTAX_10 |
Enter a value here: a number, or text in double quotes (line , column ). | Provide a value after the operator in having(). |
ONQL_ERROR_SYNTAX_11 |
The clause is repeated. Use each clause only once (line , column ). | Remove the duplicate clause. |
ONQL_ERROR_SYNTAX_12 |
Add in or an operator after the attribute, such as >, <,=,>=, <= or !=(line , column ). | Complete the having() condition with the appropriate operator and value. |
ONQL_ERROR_SYNTAX_13 |
Add an operator after the attribute, such as is, is_not, contains, does_not_contain, begins_with or ends_with (line , column ). | Specify a supported filter operator and value. |
ONQL_ERROR_SYNTAX_14 |
The value list cannot be empty. Add at least one value in double quotes, for example is ("value") (line , column ). | Provide at least one value in the list. |
Common syntax corrections
Missing sorting direction
Incorrect
sort avg(performance.cpu_usage_percentage)
Correct
sort avg(performance.cpu_usage_percentage) desc
Missing filter operator
Incorrect
filterby(monitoring_inventory.monitor_name)
Correct
filterby(monitoring_inventory.monitor_name contains "web")
Repeated clauses
Incorrect
timeperiod last_24_hours timeperiod last_7_days
Correct
timeperiod last_24_hours
Time period and time slice errors
These errors occur when the specified time period, time interval, relative expression, or custom date range is invalid or unsupported.
| Error code | Error message | How to resolve |
|---|---|---|
ONQL_ERROR_PERIOD_01 |
The time period provided in the query is invalid. | Replace the invalid time period with a supported value. |
ONQL_ERROR_PERIOD_02 |
The time period, is not available for . | Select a time period supported by the feature. |
ONQL_ERROR_PERIOD_03 |
The time slice provided in the query is invalid. | Specify a supported time slice interval. |
ONQL_ERROR_PERIOD_04 |
You cannot break down by . | Use a compatible time period and time slice combination. |
ONQL_ERROR_PERIOD_05 |
is invalid. Use a relative time expression, such as -30d, -12h, or -1d 2h 30m (m = minutes). | Correct the relative time expression. |
ONQL_ERROR_PERIOD_06 |
is invalid. Enter a time between h and h. | Specify a relative time span within the supported range. |
ONQL_ERROR_PERIOD_07 |
custom_period("", "") is not a valid range. Use dates like 2026-10-15T16:20:25+0530 (yyyy-MM-ddTHH:mm:ss+HHMM) with the start before the end. | Use valid timestamps and ensure the start date precedes the end date. Alternatively, click the calendar icon  to select a date range and automatically insert the dates in the required format. |
ONQL_ERROR_PERIOD_08 |
custom_period("", "") is longer than allows ( days). | Reduce the date range to the supported duration. |
Common time period corrections
Unsupported time slice combination
Incorrect
timeperiod last_7_days timeslice day
Correct
timeperiod last_30_days timeslice day
Invalid custom date
Incorrect
timeperiod custom_period("2026-02-30T00:00:00+0530", "2026-03-10T00:00:00+0530")
Correct
timeperiod custom_period("2026-02-28T00:00:00+0530", "2026-03-10T00:00:00+0530")
Custom Reports support time spans between one hour and two years. The time slice clause cannot follow custom_period() or custom_expression.
Column errors
Column errors occur when attributes included in a query are invalid, incomplete, duplicated, or exceed the supported limit.
| Error code | Error message | How to resolve |
|---|---|---|
ONQL_ERROR_COLUMN_01 |
is an invalid attribute. Check the namespace and the attribute name. | Verify that the attribute exists and belongs to the selected monitor category. |
ONQL_ERROR_COLUMN_02 |
is incomplete. Add the attribute name after the namespace. | Specify the complete attribute name. |
ONQL_ERROR_COLUMN_03 |
is duplicated. | Remove the duplicate attribute or aggregation. |
ONQL_ERROR_COLUMN_04 |
This query exceeds the maximum limit of columns. | Reduce the number of selected columns. |
ONQL_ERROR_COLUMN_05 |
The sort column must be included in the query. | Add the sorting attribute to include(). |
Example: Sorting by an attribute that is not included
Incorrect
reporttype="server" | include(monitoring_inventory.monitor_name) sort avg(performance.cpu_usage_percentage) desc
Correct
reporttype="server" | include(monitoring_inventory.monitor_name, avg(performance.cpu_usage_percentage)) sort avg(performance.cpu_usage_percentage) desc
A Custom Report supports a maximum of 100 columns. When multiple aggregations are applied to an attribute, each aggregation counts as a separate column.
Attribute errors
Attribute errors occur when an aggregation, operator, or namespace is incompatible with the selected attribute or feature.
| Error code | Error message | How to resolve |
|---|---|---|
ONQL_ERROR_ATTRIBUTE_01 |
Attributes of type are not available for . | Select an attribute from a namespace supported by the feature. This error is not currently raised in Custom Reports. |
ONQL_ERROR_ATTRIBUTE_02 |
The aggregate cannot be applied for . | Use an aggregation function supported by the selected feature. |
ONQL_ERROR_ATTRIBUTE_03 |
The filter operator cannot be applied for . | Replace the unsupported filter operator. |
ONQL_ERROR_ATTRIBUTE_04 |
The condition operator cannot be applied for . | Use a supported operator in having(). |
ONQL_ERROR_ATTRIBUTE_05 |
Attributes of type cannot be used as a filter value for . | Use a supported namespace in filterby(). |
ONQL_ERROR_ATTRIBUTE_06 |
Attributes of type cannot be used in having for . | Use supported performance or availability attributes in having(). |
Example: Unsupported operator in having()
Incorrect
having(avg(performance.cpu_usage_percentage) contains "80")
Correct
having(avg(performance.cpu_usage_percentage) > 80)
Value and unit errors
These errors occur when a query uses an incompatible operator, an incorrect value type, or an unsupported unit conversion.
| Error code | Error message | How to resolve |
|---|---|---|
ONQL_ERROR_VALUE_01 |
The operator cannot be applied to a attribute. | Use an operator compatible with the attribute's data type. |
ONQL_ERROR_VALUE_02 |
is not a valid value. | Enter a value that matches the expected data type. |
ONQL_ERROR_VALUE_03 |
is not a compatible unit for . | Convert the attribute to a unit within the same supported unit family. |
ONQL_ERROR_VALUE_04 |
does not support unit conversion. | Remove the unit conversion modifier from the attribute. |
Example: Invalid unit conversion
Incorrect
availability.down_time in "hours"
Correct
availability.down_time in "hrs"
Business rule validation errors
Business rule errors occur when a query is syntactically valid but violates ONQL requirements for selecting attributes, filtering, aggregation, sorting, or time periods.
Multiple validation rules can return ONQL_ERROR_RULE. The associated rule identifier helps distinguish the underlying issue.
| Rule identifier | Error message | How to resolve |
|---|---|---|
ONQL_ERROR_RULE_01 |
Include monitoring_inventory.child.name when selecting child attributes as columns. | Add the child name attribute when retrieving child entity data. |
ONQL_ERROR_RULE_02 |
A having clause can contain only one aggregation function. | Use separate conditions instead of multiple aggregations within one condition. |
ONQL_ERROR_RULE_03 |
Include in the query to apply a filter. | Add the filtered attribute to include(). |
ONQL_ERROR_RULE_04 |
Only inventory attributes can be used with filterby for . | Use inventory attributes in filterby(). |
ONQL_ERROR_RULE_05 |
cannot be used as a filter. | Select an attribute that supports filtering. |
ONQL_ERROR_RULE_06 |
Include in the query before using it in a having clause. | Add the attribute to include(). |
ONQL_ERROR_RULE_07 |
The having clause is applicable only for performance and availability values. is . | Use supported performance or availability attributes. |
ONQL_ERROR_RULE_08 |
timeperiod is mandatory when a time-based attribute like "" is selected. | Specify a valid time period. |
ONQL_ERROR_RULE_09 |
Only performance attributes can be aggregated. "" belongs to . | Apply aggregation functions to performance attributes only. |
ONQL_ERROR_RULE_10 |
"" cannot be compared with an empty value. Enter a value between the quotes. | Provide a non-empty comparison value. |
ONQL_ERROR_RULE_11 |
"" must be one of the included columns before you can sort on it. | Add the sorting attribute to include(). |
ONQL_ERROR_RULE is returned when a business validation error occurs but does not match any of the specific conditions listed above.
Common business rule corrections
Filtering by an attribute that is not included
Incorrect
reporttype="server" | include(monitoring_inventory.monitor_name) filterby(monitoring_inventory.tags is "prod")
Correct
reporttype="server" | include(monitoring_inventory.monitor_name, monitoring_inventory.tags) filterby(monitoring_inventory.tags is "prod")
Aggregating a non-performance attribute
Incorrect
include(avg(availability.down_time))
Correct
include(availability.down_time)
Missing time period for a time-based attribute
Incorrect
reporttype="server" | include(monitoring_inventory.monitor_name, availability.down_time)
Correct
reporttype="server" | include(monitoring_inventory.monitor_name, availability.down_time) timeperiod last_24_hours
Troubleshooting ONQL queries
If your query fails validation, follow these steps to identify and resolve the issue:
- Review the error message: Identify the error code and the corresponding description displayed in the query editor.
- Locate the issue: For syntax errors, use the line and column details to identify the affected expression.
- Check the query structure: Verify that mandatory clauses, operators, parentheses, and separators are correctly specified.
- Validate attributes and values: Ensure that the selected attributes are supported by the monitor category and that their operators, aggregations, and units are compatible.
- Correct and rerun the query: Update the query based on the error message and preview the results to verify that the intended data is retrieved.
The ONQL editor provides context-aware suggestions to help you identify supported attributes and query components. Press Ctrl + Space on Windows, Option + Space on macOS, or Shift + Space on Linux to view available suggestions.