### Summary The query DSL schema and the query language guide say `rel_types` is optional on a path finding query when both endpoints use `node_ids`, but the server rejects every path finding query without `rel_types`. ### Expected behavior The schema, the guide and the Orbit skill state the rule the server applies: every path finding query needs `rel_types`. ### Actual behavior `GET /api/v4/orbit/schema/dsl` (DSL 12.1.9 on GitLab.com) describes `rel_types` as "Required when an endpoint is constrained by filters or id_range; optional when both endpoints use node_ids." A query that follows it is rejected with `400 {"code":"compile_error","message":"schema violation: path_finding requires rel_types to bound fan-out; without it the frontier expands over every edge type"}`. The path finding example of the query language guide also runs from a project to a user through relationship types that point from the user to the project, so it returns no rows even when the path exists. ### Steps to reproduce 1. `glab api "orbit/schema/dsl?response_format=raw" | jq '."$defs".PathConfig.properties.rel_types.description'` 2. Send a path query with both endpoints on `node_ids` and no `rel_types`, for example from a user to a project they belong to: `{"query":{"query_type":"path_finding","nodes":[{"id":"u","entity":"User","node_ids":[<user id>]},{"id":"p","entity":"Project","node_ids":[<project id>]}],"path":{"type":"shortest","from":"u","to":"p","max_depth":2}}}`. It answers `400` with the message above. 3. Add `"rel_types": ["MEMBER_OF", "CONTAINS"]` to `path`. It answers `200` with the path. ### Environment Which Orbit are you using? - [x] **Orbit Remote**: the hosted graph on GitLab.com (`glab orbit remote`, MCP, GitLab Duo, or the REST API). - [ ] **Orbit Local**: runs on your machine (the `orbit` binary or `glab orbit local`). **Orbit Remote** - GitLab.com group or project path (e.g. `gitlab-org/gitlab`): a private project in my own group - Access method: REST API - Approximate time of the failure (include timezone, or use UTC): 2026-09-28, 15:52 UTC ### Logs <details><summary>Expand logs</summary> ```plaintext POST /api/v4/orbit/query {"query":{"query_type":"path_finding","nodes":[{"id":"u","entity":"User","node_ids":[15767218]},{"id":"p","entity":"Project","node_ids":[<ID of a private project in my group>]}],"path":{"type":"shortest","from":"u","to":"p","max_depth":2}}} -> 400 {"code":"compile_error","message":"schema violation: path_finding requires rel_types to bound fan-out; without it the frontier expands over every edge type"} The same with "rel_types":["MEMBER_OF","CONTAINS"] -> 200, one path: User -MEMBER_OF-> Group -CONTAINS-> Project The guide's example with my IDs, Project -> User, rel_types CREATOR, AUTHORED, IN_PROJECT -> 200, row_count 0 The same, User -> Project -> 200, row_count 2 (CREATOR; AUTHORED then IN_PROJECT) ``` </details> ### Workaround Always send `rel_types`, and choose relationship types that point from the `from` node toward the `to` node. ### Additional context The rule became unconditional in !1621, and its test pins the `node_ids` case. The description kept the earlier condition through !2145, and #1046 plans to reword it on the same premise. Found while maintaining [gitlab-mcp-server](https://github.com/jmrplens/gitlab-mcp-server), which hands this schema to AI assistants. The fix is proposed in !2650. cc @michaelusa @aalgutifan ### Checklist - [x] Reproduced on the latest available version. - [x] Searched existing issues for duplicates. - [x] Included minimal, reliable reproduction steps. - [x] Attached relevant logs and environment details. - [x] Removed sensitive information from logs/configs. <details> <summary><b>Agent context</b>: extended analysis, hypothesis chains, file walkthroughs</summary> **Where the statement is** (main at `1c43d9f0`): - [`config/schemas/graph_query.schema.json:636`](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/1c43d9f0e984be5ebd6825bf477773953b788a3b/config/schemas/graph_query.schema.json#L636), `PathConfig.rel_types.description`. GitLab.com serves it verbatim through `GET /orbit/schema/dsl` in both formats and through the `get_query_dsl` agent command. - [`docs/source/remote/queries/query-language.md:566`](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/1c43d9f0e984be5ebd6825bf477773953b788a3b/docs/source/remote/queries/query-language.md#L566) and [`:568-570`](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/1c43d9f0e984be5ebd6825bf477773953b788a3b/docs/source/remote/queries/query-language.md#L568-570), published at https://docs.gitlab.com/orbit/remote/queries/query-language/. - `skills/orbit/references/query_language.md:566` and `:568-570`, the synced copy served at `GET /orbit/skills/orbit/references/query_language.md`. - [`skills/orbit/references/recipes.md:419-420`](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/1c43d9f0e984be5ebd6825bf477773953b788a3b/skills/orbit/references/recipes.md#L419-420): "`rel_types` is required when either endpoint uses `filters`." **What the code does**: `check_path` in [`crates/query-engine/compiler/src/passes/validate.rs:1221-1231`](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/1c43d9f0e984be5ebd6825bf477773953b788a3b/crates/query-engine/compiler/src/passes/validate.rs#L1221-1231) rejects any path query whose `rel_types` is empty ("rel_types is always required for pathfinding ... Even pinned endpoints can hit hub nodes"), and [`validate.rs:2532-2541`](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/1c43d9f0e984be5ebd6825bf477773953b788a3b/crates/query-engine/compiler/src/passes/validate.rs#L2532-2541) asserts that two projects pinned by `node_ids` with no `rel_types` are rejected. **History**: !1093 (`e735f646`, 2026-04-27) made `rel_types` required for filtered endpoints, which the description and the guide (!1235) then described correctly. !1621 (`da7a4bcf`, 2026-06-09) made it unconditional without touching them. !2145 (`66f84f8e`, 2026-07-29) shortened the description and kept the condition. #1046 proposes "the rule becomes 'endpoint pinned to concrete IDs' regardless of spelling", which assumes the condition still applies. **The guide's path example**: [`query-language.md:572-588`](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/blob/1c43d9f0e984be5ebd6825bf477773953b788a3b/docs/source/remote/queries/query-language.md#L572-588) runs from `Project` to `User` through `CREATOR`, `AUTHORED` and `IN_PROJECT`, which all point from the user side toward the project. `recipes.md:422` already warns that path finding follows `rel_types` only in their defined direction, and the corpus expects a project-to-project path to be empty (`fixtures/queries/corpus/sdlc.yaml`, `q25`). Measured on GitLab.com with my own IDs: 0 rows in the guide's direction, 2 paths the other way. **Proposed change** (!2650, from the community fork): - Schema description: "Relationship types to traverse, each followed only in its defined direction. Required, including when both endpoints use node_ids." - Guide and its skill copy (synced with `mise run skill:sync:orbit`): the table row says "Required."; the paragraph says a path query without `rel_types` is rejected even when both endpoints use `node_ids`; a new paragraph states the direction rule; the example runs from `User` to `Project`. - `recipes.md`: "`rel_types` is required on every path query, including when both endpoints use `node_ids`." - `skills/orbit/SKILL.md` version `0.32.2` to `0.32.3`, as `references/maintaining.md` requires. **Left for you to decide**: - `config/versions.yaml` bumps `query_dsl` when accepted queries change, and this change accepts nothing new. A patch bump would still tell clients that cache the schema by version to fetch it again. - Adding `rel_types` to `PathConfig.required` with `minItems: 1` would let clients that validate against the schema catch the mistake before calling the server. It changes the published schema and the error text, so I left it out of the merge request. </details>