alibaba/nacos · error · NacosApiException

400

400

Error message

Unsupported ARD orderBy field: {field}

What it means

Thrown by parseOrderBy() when the orderBy field (after aliasing) is not one of the allowed sort keys. Accepted: displayName (alias 'name'), updatedAt (alias 'updated_at'), or identifier. Any other first token yields PARAMETER_VALIDATE_ERROR (HTTP 400). The optional second token may be 'desc' (case-insensitive) for descending order.

Source

Thrown at ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/service/ard/ArdSearchServiceImpl.java:604

        return Math.min(pageSize, MAX_LIST_PAGE_SIZE);
    }
    
    private void parseOrderBy(String orderBy, ListContext context) throws NacosApiException {
        context.orderBy = "updatedAt";
        context.orderDescending = true;
        if (StringUtils.isBlank(orderBy)) {
            return;
        }
        String[] parts = orderBy.trim().split("\\s+");
        String field = parts[0];
        if ("name".equalsIgnoreCase(field)) {
            field = "displayName";
        } else if ("updated_at".equalsIgnoreCase(field)) {
            field = "updatedAt";
        }
        if (!"displayName".equals(field) && !"updatedAt".equals(field)
            && !"identifier".equals(field)) {
            throw new NacosApiException(NacosException.INVALID_PARAM,
                ErrorCode.PARAMETER_VALIDATE_ERROR, "Unsupported ARD orderBy field: " + field);
        }
        context.orderBy = field;
        context.orderDescending = parts.length > 1 && "desc".equalsIgnoreCase(parts[1]);
    }
    
    private Map<String, List<String>> normalizeFilter(ArdSearchQuery query)
        throws NacosApiException {
        Map<String, List<String>> result = new LinkedHashMap<>();
        if (query.getFilter() != null && !query.getFilter().isEmpty()) {
            for (Map.Entry<String, Object> entry : query.getFilter().entrySet()) {
                addFilter(result, entry.getKey(),
                    normalizeFilterValues(entry.getKey(), entry.getValue()));
            }
        }
        if (query.getFilters() == null || query.getFilters().isEmpty()) {
            return result;
        }

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Use orderBy one of: name, updated_at, displayName, updatedAt, or identifier.
2. Append ' desc' for descending order (e.g. 'updatedAt desc'); ascending is the default otherwise.
3. If you need to sort by an unsupported field, request it as a feature and sort client-side in the meantime.
4. Leave orderBy unset to accept the server default (updatedAt desc).

Example fix

// before
req.setOrderBy("createdAt");

// after
req.setOrderBy("updatedAt desc");
// or: "name", "updated_at", "identifier"

private static final Set<String> ORDER_BY_FIELDS =
    Set.of("displayName", "updatedAt", "identifier");
private static final Map<String,String> ORDER_BY_ALIASE = Map.of(
    "name", "displayName", "updated_at", "updatedAt");

public String normalizeOrderBy(String orderBy) {
    if (orderBy == null || orderBy.trim().isEmpty()) return "updatedAt";
    String[] parts = orderBy.trim().split("\\s+");
    String field = ORDER_BY_ALIASE.getOrDefault(parts[0].toLowerCase(), parts[0]);
    if (!ORDER_BY_FIELDS.contains(field)) {
        throw new IllegalArgumentException(
            "orderBy must be one of " + ORDER_BY_FIELDS + " (aliases: name, updated_at)");
    }
    return field;
}

boolean isValidOrderBy(String orderBy) {
    if (orderBy == null || orderBy.trim().isEmpty()) return true;
    String f = orderBy.trim().split("\\s+")[0].toLowerCase();
    return Set.of("name","updated_at","displayname","updatedat","identifier").contains(f);
}

When it happens

Trigger: Sending orderBy=createdAt, orderBy=version, orderBy=status, or orderBy=relevance. The aliasing only maps 'name'->'displayName' and 'updated_at'->'updatedAt'; everything else must already be the canonical internal name.

Common situations: Client assumes more sortable fields than supported; forwards a database column name not exposed by ARD; uses a camelCase field that isn't in the allowlist; expects createdAt to be sortable when only updatedAt is.

Related errors

• PARAMETER_VALIDATE_ERROR
• PARAMETER_VALIDATE_ERROR
• DATA_ACCESS_ERROR
• PARAMETER_MISSING
• INVALID_PARAM

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/e4a852de9a493bbd. Report an issue: GitHub.