theonedev/onedev · error · ExplicitException

Cannot order by field:

Error message

Cannot order by field: 

What it means

AgentQuery.parse validates each order-by field name against the query's fixed SORT_FIELDS set; an unknown field cannot be mapped to a sort property and parsing aborts. The message carries the offending field name.

Source

Thrown at server-core/src/main/java/io/onedev/server/search/entity/agent/AgentQuery.java:214

						return new AndCriteria<>(childCriterias);
					}

					@Override
					public Criteria<Agent> visitNotCriteria(NotCriteriaContext ctx) {
						return new NotCriteria<>(visit(ctx.criteria()));
					}

				}.visit(criteriaContext);
			} else {
				agentCriteria = null;
			}

			List<EntitySort> agentSorts = new ArrayList<>();
			for (OrderContext order: queryContext.order()) {
				var fieldName = getValue(order.Quoted().getText());
				var sortField = SORT_FIELDS.get(fieldName);
				if (sortField == null)
					throw new ExplicitException("Cannot order by field: " + fieldName);
				
				EntitySort agentSort = new EntitySort();
				agentSort.setField(fieldName);
				if (order.direction != null) {
					if (order.direction.getText().equals("desc"))
						agentSort.setDirection(DESCENDING);
					else
						agentSort.setDirection(ASCENDING);
				} else {
					agentSort.setDirection(sortField.getDefaultDirection());
				}
				agentSorts.add(agentSort);
			}
			
			return new AgentQuery(agentCriteria, agentSorts);
		} else {
			return new AgentQuery();
		}

View on GitHub (pinned to d44925c47c)

Solutions

1. Use only fields listed in AgentQuery.SORT_FIELDS (e.g. "name")
2. Fix the field-name spelling
3. Sort client-side if the field isn't server-sortable

Example fix

// before
q = "order by description"
// after
q = "order by \"name\""

if (!AgentQuery.SORT_FIELDS.containsKey(sortField)) throw new IllegalArgumentException("not sortable: " + sortField);

try { new AgentQuery(q); } catch (ExplicitException e) { /* drop or replace the order clause */ }

When it happens

Trigger: Supplying an 'order by' field in an agent query that is not among the allowed sort fields, e.g. order("description") when only id/name fields are sortable.

Common situations: Ordering by an agent attribute or custom field; typo in the field name; assuming all query fields are also sortable.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

• Error parsing query
• Malformed query
• Criteria '' is not supported here
• Unexpected operator:
• Attribute not found:

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/c958c6c3e3b96e92. Report an issue: GitHub.