# INVALID_GROUP_BY_PATH — groupBy entry is not a scalar JSONPath

Raised by `POST /api/entity/stats/{entityName}/{modelVersion}/query`. Every `groupBy` entry other than `state` must match the wire JSONPath grammar — a re…

<em>cyoda-go version <a href="https://github.com/Cyoda/cyoda-go/releases/tag/v0.8.4">0.8.4</a></em>

# errors.INVALID_GROUP_BY_PATH

## NAME

INVALID_GROUP_BY_PATH — a `groupBy` entry is neither the reserved `state` token nor a JSONPath that denotes a single scalar.

## SYNOPSIS

HTTP: `400` `Bad Request`. Retryable: `no`.

## DESCRIPTION

Raised by `POST /api/entity/stats/{entityName}/{modelVersion}/query`. Every `groupBy` entry other than `state` must match the wire JSONPath grammar — a required `$.` leader followed by dot-separated segments of ASCII letters, digits, `_` and `-`:

```
path    = "$." segment ( "." segment )*
segment = 1*( ALPHA / DIGIT / "_" / "-" )
```

Rejected here: a missing leader (`country` — write `$.country`), bracket-quoted property access (`$['country']`, `$.['country']`), array projections and subscripts (`$.items[*]`, `$.items[0]` — address a position as an ordinary segment, `$.items.0`), recursive descent (`$..name`), filter expressions, empty, leading, trailing or doubled dots, whitespace, quotes, and non-ASCII characters.

Array subscripts are rejected even though a `condition` `jsonPath` accepts them: a group-by dimension must resolve to one scalar, and a projection has no such value. The check runs at the API boundary before any storage backend, so a request is rejected identically whichever execution path would have served it. The message names the offending entry and the reason.

The token `state` is accepted in `groupBy` only, and carries no `$.` leader — it names lifecycle state, not a path. A payload field literally called `state` is written `$.state`.

## SEE ALSO

- errors
- crud
- errors.INVALID_AGGREGATION_FIELD
- errors.INVALID_FIELD_PATH

## See also

- [`cyoda help errors`](/help/errors/) — Every error response from the Cyoda REST API carries a structured `errorCode` in the `properties` object. Multiple codes may share the same HTTP status. Programmatic handling keys on `errorCode`, not HTTP status.
- [`cyoda help crud`](/help/crud/) — Entities are instances of models. Each entity has a UUID, a model reference (`entityName`, `modelVersion`), and a lifecycle state managed by the workflow engine. Creating an entity requires the referenced model to be in `LOCKED` state. All write operations run within a Cyoda transaction and return a `transactionId` alongside the affected entity IDs.
- [`cyoda help errors INVALID_AGGREGATION_FIELD`](/help/errors/invalid_aggregation_field/) — Raised by `POST /api/entity/stats/{entityName}/{modelVersion}/query`. An aggregation `field` obeys exactly the grammar a `groupBy` path does — a required `$.` leader followed by dot-separated segments of ASCII letters, digits, `_` and `-`, with no bracket-quoted access, array subscript or projection, recursive descent, whitespace or non-ASCII character. See `cyoda help errors INVALID_GROUP_BY_PATH` for the grammar and the rejected spellings; the message names the offending field and the reason.
- [`cyoda help errors INVALID_FIELD_PATH`](/help/errors/invalid_field_path/) — Three checks emit this code.

## Raw formats

- [`/help/errors/invalid_group_by_path.json`](/help/errors/invalid_group_by_path.json) — full descriptor (matches `GET /help/{topic}` envelope)
- [`/help/errors/invalid_group_by_path.md`](/help/errors/invalid_group_by_path.md) — body only