Add errors for unsupported combinations with path modes (#399)

New error codes (and one message update) for path mode semantic checking

---------

Co-authored-by: Reneta Popova <[email protected]>

Author: dogofbrian

modules/ROOT/content-nav.adoc

@@ -326,6 +326,8 @@
 **** xref:errors/gql-errors/42N57.adoc[]
 **** xref:errors/gql-errors/42N58.adoc[]
 **** xref:errors/gql-errors/42N59.adoc[]
+**** xref:errors/gql-errors/42N60.adoc[]
+**** xref:errors/gql-errors/42N61.adoc[]
 **** xref:errors/gql-errors/42N62.adoc[]
 **** xref:errors/gql-errors/42N63.adoc[]
 **** xref:errors/gql-errors/42N64.adoc[]

modules/ROOT/pages/errors/gql-errors/42I39.adoc

@@ -1,7 +1,36 @@
+:page-role: new-2025.11
 = 42I39
 
 == Status description
-error: syntax error or access rule violation - invalid use of shortest path function. Mixing the `{ <<fun>> }` function with path selectors or explicit match modes is not allowed.
+error: syntax error or access rule violation - invalid use of shortest path function. Mixing the `{ <<fun>> }` function with path selectors, explicit match modes, or explicit path modes is not allowed.
+
+== Example scenario
+For example, in the following query `REPEATABLE ELEMENTS` is used with the `shortestPath()` function:
+
+[source,cypher]
+----
+MATCH p = ACYCLIC shortestPath((:A)-[:R*0..10]->(:B))
+  WHERE any(x IN nodes(p) WHERE x:X)
+RETURN p
+----
+This will result in an error with GQLSTATUS xref:errors/gql-errors/42001.adoc[42001], with a cause detailed in xref:errors/gql-errors/42I39.adoc[42I39] and the following status description:
+
+[source]
+----
+error: syntax error or access rule violation - invalid use of shortest path function. Mixing the `shortestPath()` function with path selectors, explicit match modes, or explicit path modes is not allowed.
+----
+
+== Possible solution
+Replace `shortestPath()` with the `SHORTEST 1` path selector, and `allShortestPaths()` with the `SHORTEST ALL` path selector.
+
+For example, the query above can be rewritten as:
+
+[source,cypher]
+----
+MATCH p = SHORTEST 1 ACYCLIC (:A)-[:R*0..10]->(:B)
+  WHERE any(x IN nodes(p) WHERE x:X)
+RETURN p
+----
 
 ifndef::backend-pdf[]
 [discrete.glossary]

modules/ROOT/pages/errors/gql-errors/42N60.adoc

@@ -0,0 +1,27 @@
+:page-role: new-2025.11
+= 42N60
+
+== Status description
+error: syntax error or access rule violation - unsupported combination of match mode and path mode. `REPEATABLE ELEMENTS` with `{ <<pathMode>> }` path mode is not supported.
+
+== Example scenario
+For example, in the following query `REPEATABLE ELEMENTS` is used with the `TRAIL` path mode:
+
+[source,cypher]
+----
+MATCH REPEATABLE ELEMENTS p = TRAIL (:A)-[:R]->{,10}(:B)
+RETURN p
+----
+This will result in an error with GQLSTATUS xref:errors/gql-errors/42001.adoc[42001], with a cause detailed in xref:errors/gql-errors/42N60.adoc[42N60] and the following status description:
+
+[source]
+----
+error: syntax error or access rule violation - unsupported combination of match mode and path mode. `REPEATABLE ELEMENTS` with `TRAIL` path mode is not supported.
+----
+
+ifndef::backend-pdf[]
+[discrete.glossary]
+== Glossary
+
+include::partial$glossary.adoc[]
+endif::[]

modules/ROOT/pages/errors/gql-errors/42N61.adoc

@@ -0,0 +1,42 @@
+:page-role: new-2025.11
+= 42N61
+
+== Status description
+error: syntax error or access rule violation - unsupported mixing of different path modes. Mixing `{ <<pathModeList>> }` in the same graph pattern is not supported. Split the pattern into separate `MATCH` clauses instead.
+
+== Example scenario
+For example, in the following query `TRAIL` and `ACYCLIC` are used:
+
+[source,cypher]
+----
+MATCH p = ACYCLIC (a:A)-[:P]->+(b:B),
+      q = TRAIL (b)-[:Q]->+(a)
+RETURN p, q
+----
+This will result in an error with GQLSTATUS xref:errors/gql-errors/42001.adoc[42001], with a cause detailed in xref:errors/gql-errors/42N61.adoc[42N61] and the following status description:
+
+[source]
+----
+error: syntax error or access rule violation - unsupported mixing of different path modes. Mixing `ACYCLIC` and  `TRAIL` in the same graph pattern is not supported. Split the pattern into separate `MATCH` clauses instead.
+----
+
+== Possible solution
+Split the graph pattern into separate `MATCH` clauses and use predicates to enforce relationship uniqueness across the set of paths.
+
+For example, the above query can be rewritten as:
+
+[source,cypher]
+----
+MATCH p = ACYCLIC (a:A)-[r1:P]->+(b:B)
+MATCH q = TRAIL (b)-[r2:Q WHERE NOT r2 IN r1]->+(a)
+RETURN p, q
+----
+
+Here the predicate `NOT r2 IN r1` ensures that the relationships in path `q` do not overlap with those in path `p`, replicating the effect of Cypher's default match mode `DIFFERENT RELATIONSHIPS`.
+
+ifndef::backend-pdf[]
+[discrete.glossary]
+== Glossary
+
+include::partial$glossary.adoc[]
+endif::[]

modules/ROOT/pages/errors/gql-errors/index.adoc

@@ -977,9 +977,10 @@ Status description:: error: syntax error or access rule violation - invalid use
 
 Status description:: error: syntax error or access rule violation - invalid use of `RETURN`. `RETURN ...` can only be used at the end of a query or subquery.
 
+[role=label--new-2025.11]
 === xref:errors/gql-errors/42I39.adoc[42I39]
 
-Status description:: error: syntax error or access rule violation - invalid use of shortest path function. Mixing the `{ <<fun>> }` function with path selectors or explicit match modes is not allowed.
+Status description:: error: syntax error or access rule violation - invalid use of shortest path function. Mixing the `{ <<fun>> }` function with path selectors, explicit match modes, or explicit path modes is not allowed.
 
 === xref:errors/gql-errors/42I40.adoc[42I40]
 
@@ -1337,6 +1338,16 @@ Status description:: error: syntax error or access rule violation - unsupported
 
 Status description:: error: syntax error or access rule violation - variable already defined. Variable `{ <<variable>> }` already declared.
 
+[role=label--new-2025.11]
+=== xref:errors/gql-errors/42N60.adoc[42N60]
+
+Status description:: error: syntax error or access rule violation - unsupported combination of match mode and path mode. `REPEATABLE ELEMENTS` with `{ <<pathMode>> }` path mode is not supported.
+
+[role=label--new-2025.11]
+=== xref:errors/gql-errors/42N61.adoc[42N61]
+
+Status description:: error: syntax error or access rule violation - unsupported mixing of different path modes. Mixing `{ <<pathModeList>> }` in the same graph pattern is not supported. Split the pattern into separate `MATCH` clauses instead.
+
 === xref:errors/gql-errors/42N62.adoc[42N62]
 
 Status description:: error: syntax error or access rule violation - variable not defined. Variable `{ <<variable>> }` not defined.

modules/ROOT/partials/glossary.adoc

@@ -81,6 +81,8 @@
 [[param]]$param:: Parameter name, for example, `$pattern`.
 [[paramList]]$paramList:: A list of parameters, for example `$pattern, $prop`.
 [[pat]]$pat:: Pattern, for example, `(:Person)`.
+[[pathMode]]$pathMode:: GPM path mode, for example, `ACYCLIC`.
+[[pathModeList]]$pathModeList:: A list of GPM path modes, for example, `TRAIL, ACYCLIC`.
 [[port]]$port:: Port name, for example, `6362`.
 [[portList]]$portList:: A list of port names, for example, `6362, 6000, 7000`.
 [[pos]]$pos:: A position, for example, in a sequence, for example, `2`