diff --git a/modules/ROOT/pages/errors/gql-errors/22NA5.adoc b/modules/ROOT/pages/errors/gql-errors/22NA5.adoc index 2038d535..4d6f947b 100644 --- a/modules/ROOT/pages/errors/gql-errors/22NA5.adoc +++ b/modules/ROOT/pages/errors/gql-errors/22NA5.adoc @@ -1,7 +1,7 @@ = 22NA5 == Status description -error: data exception - invalid property based access control rule involving IS `NULL`. The property value access rule pattern `{ <> }` always evaluates to `NULL`. Use `IS NULL` instead. +error: data exception - invalid property based access control rule involving `IS NULL`. The property value access rule pattern `{ <> }` always evaluates to `NULL`. Use `IS NULL` instead. ifndef::backend-pdf[] [discrete.glossary] diff --git a/modules/ROOT/pages/errors/gql-errors/42I33.adoc b/modules/ROOT/pages/errors/gql-errors/42I33.adoc index f6311a99..d5a12561 100644 --- a/modules/ROOT/pages/errors/gql-errors/42I33.adoc +++ b/modules/ROOT/pages/errors/gql-errors/42I33.adoc @@ -1,7 +1,7 @@ = 42I33 == Status description -error: syntax error or access rule violation - invalid use of NOT NULL. Closed Dynamic Union types cannot be appended with `NOT NULL`, specify `NOT NULL` on inner types instead. +error: syntax error or access rule violation - invalid use of `NOT NULL`. Closed Dynamic Union types cannot be appended with `NOT NULL`, specify `NOT NULL` on inner types instead. ifndef::backend-pdf[] [discrete.glossary] diff --git a/modules/ROOT/pages/errors/gql-errors/42I42.adoc b/modules/ROOT/pages/errors/gql-errors/42I42.adoc index 756b30f2..e146d130 100644 --- a/modules/ROOT/pages/errors/gql-errors/42I42.adoc +++ b/modules/ROOT/pages/errors/gql-errors/42I42.adoc @@ -1,7 +1,7 @@ = 42I42 == Status description -error: syntax error or access rule violation - invalid use of YIELD. Cannot use YIELD on a call to a void procedure. +error: syntax error or access rule violation - invalid use of `YIELD`. Cannot use `YIELD` on a call to a void procedure. ifndef::backend-pdf[] [discrete.glossary] diff --git a/modules/ROOT/pages/errors/gql-errors/42I50.adoc b/modules/ROOT/pages/errors/gql-errors/42I50.adoc index 6ee50d96..145fccfb 100644 --- a/modules/ROOT/pages/errors/gql-errors/42I50.adoc +++ b/modules/ROOT/pages/errors/gql-errors/42I50.adoc @@ -1,7 +1,7 @@ = 42I50 == Status description -error: syntax error or access rule violation - token name too long. Invalid input `{ <> } ..`. A `{ <> }` name cannot be longer than `{ <> }`. +error: syntax error or access rule violation - token name too long. Invalid input `{ <> }..`. A `{ <> }` name cannot be longer than `{ <> }`. ifndef::backend-pdf[] [discrete.glossary] diff --git a/modules/ROOT/pages/errors/gql-errors/42N18.adoc b/modules/ROOT/pages/errors/gql-errors/42N18.adoc index 94fdc380..133c3c9d 100644 --- a/modules/ROOT/pages/errors/gql-errors/42N18.adoc +++ b/modules/ROOT/pages/errors/gql-errors/42N18.adoc @@ -3,6 +3,8 @@ == Status description error: syntax error or access rule violation - read-only database. The database is in read-only mode. + + ifndef::backend-pdf[] [discrete.glossary] == Glossary diff --git a/modules/ROOT/pages/errors/gql-errors/42N44.adoc b/modules/ROOT/pages/errors/gql-errors/42N44.adoc index 6dd4da68..117a4346 100644 --- a/modules/ROOT/pages/errors/gql-errors/42N44.adoc +++ b/modules/ROOT/pages/errors/gql-errors/42N44.adoc @@ -2,7 +2,7 @@ == Status description -error: syntax error or access rule violation - inaccessible variable. It is not possible to access the variable `{ <> }` declared before the `{ <> }` clause when using `DISTINCT` or an aggregation. +error: syntax error or access rule violation - inaccessible variable. It is not possible to access the variable `{ <> }` declared before the `{ <> }` clause when using `DISTINCT` or an aggregation. diff --git a/modules/ROOT/pages/errors/gql-errors/42N73.adoc b/modules/ROOT/pages/errors/gql-errors/42N73.adoc index 85652588..61af706b 100644 --- a/modules/ROOT/pages/errors/gql-errors/42N73.adoc +++ b/modules/ROOT/pages/errors/gql-errors/42N73.adoc @@ -1,7 +1,7 @@ = 42N73 == Status description -error: syntax error or access rule violation - invalid placement of `USE` clause. The `USE` clause must be the first clause of a query or an operand to `... UNION ...` . In a `CALL` sub-query, it can also be the second clause if the first clause is an importing WITH. +error: syntax error or access rule violation - invalid placement of `USE` clause. The `USE` clause must be the first clause of a query or an operand to `... UNION ...` . In a `CALL` sub-query, it can also be the second clause if the first clause is an importing `WITH`. ifndef::backend-pdf[] [discrete.glossary] diff --git a/modules/ROOT/pages/errors/gql-errors/50N10.adoc b/modules/ROOT/pages/errors/gql-errors/50N10.adoc index d2401612..d59352ce 100644 --- a/modules/ROOT/pages/errors/gql-errors/50N10.adoc +++ b/modules/ROOT/pages/errors/gql-errors/50N10.adoc @@ -3,6 +3,8 @@ == Status description error: general processing exception - index drop failed. Unable to drop `{ <> }`. + + ifndef::backend-pdf[] [discrete.glossary] == Glossary diff --git a/modules/ROOT/pages/errors/gql-errors/50N15.adoc b/modules/ROOT/pages/errors/gql-errors/50N15.adoc index 88f259b1..efabca22 100644 --- a/modules/ROOT/pages/errors/gql-errors/50N15.adoc +++ b/modules/ROOT/pages/errors/gql-errors/50N15.adoc @@ -3,6 +3,9 @@ == Status description error: general processing exception - unsupported index operation. The system attemped to execute an unsupported operation on index `{ <> }`. See debug.log for more information. + + + ifndef::backend-pdf[] [discrete.glossary] == Glossary diff --git a/modules/ROOT/pages/errors/gql-errors/51N61.adoc b/modules/ROOT/pages/errors/gql-errors/51N61.adoc index a430fb7e..aa7832d0 100644 --- a/modules/ROOT/pages/errors/gql-errors/51N61.adoc +++ b/modules/ROOT/pages/errors/gql-errors/51N61.adoc @@ -3,6 +3,8 @@ == Status description error: system configuration or operation exception - index population failed. Index `{ <> }` population failed. + + ifndef::backend-pdf[] [discrete.glossary] == Glossary diff --git a/modules/ROOT/pages/errors/gql-errors/51N62.adoc b/modules/ROOT/pages/errors/gql-errors/51N62.adoc index 91ed9b1b..0fc056f1 100644 --- a/modules/ROOT/pages/errors/gql-errors/51N62.adoc +++ b/modules/ROOT/pages/errors/gql-errors/51N62.adoc @@ -3,6 +3,8 @@ == Status description error: system configuration or operation exception - index is in a failed state. Unable to use index `{ <> }` because it is in a failed state. See logs for more information. + + ifndef::backend-pdf[] [discrete.glossary] == Glossary diff --git a/modules/ROOT/pages/errors/gql-errors/53N35.adoc b/modules/ROOT/pages/errors/gql-errors/53N35.adoc index 20062cba..cf93d59e 100644 --- a/modules/ROOT/pages/errors/gql-errors/53N35.adoc +++ b/modules/ROOT/pages/errors/gql-errors/53N35.adoc @@ -3,6 +3,8 @@ == Status description error: function exception - function compilation failed. Failed to compile function defined in `{ <> }`: `{ <> }` + + ifndef::backend-pdf[] [discrete.glossary] == Glossary diff --git a/modules/ROOT/pages/errors/gql-errors/53N37.adoc b/modules/ROOT/pages/errors/gql-errors/53N37.adoc index 9732e226..2f02f19e 100644 --- a/modules/ROOT/pages/errors/gql-errors/53N37.adoc +++ b/modules/ROOT/pages/errors/gql-errors/53N37.adoc @@ -3,6 +3,8 @@ == Status description error: function exception - function execution error. Execution of the function `{ <> }` failed. + + ifndef::backend-pdf[] [discrete.glossary] == Glossary diff --git a/modules/ROOT/pages/errors/gql-errors/53U00.adoc b/modules/ROOT/pages/errors/gql-errors/53U00.adoc index dbea11fb..bf014689 100644 --- a/modules/ROOT/pages/errors/gql-errors/53U00.adoc +++ b/modules/ROOT/pages/errors/gql-errors/53U00.adoc @@ -3,6 +3,8 @@ == Status description error: function exception - custom function execution error cause. Execution of the function `{ <> }` failed due to `{ <> }`: `{ <> }`. + + ifndef::backend-pdf[] [discrete.glossary] == Glossary diff --git a/modules/ROOT/pages/errors/gql-errors/index.adoc b/modules/ROOT/pages/errors/gql-errors/index.adoc index 0dfdfd04..2006dab9 100644 --- a/modules/ROOT/pages/errors/gql-errors/index.adoc +++ b/modules/ROOT/pages/errors/gql-errors/index.adoc @@ -1,3 +1,6 @@ +// This is an automatically generated file. Do not edit it directly. It is generated from the templates/gql-index-template.adoc file and should be edited there. + + :description: This section describes the GQLSTATUS errors that Neo4j can return, grouped by category, and an example of when they can occur. [[neo4j-gqlstatus-errors]] @@ -29,12 +32,10 @@ Status description:: error: connection exception - transaction resolution unknow Status description:: error: connection exception - unable to connect to database. Unable to connect to database `{ <> }`. Unable to get bolt address of the leader. Check the status of the database. Retrying your request at a later time may succeed. - === xref:errors/gql-errors/08N01.adoc[08N01] Status description:: error: connection exception - unable to write to database. Unable to write to database `{ <> }` on this server. Server-side routing is disabled. Either connect to the database leader directly or enable server-side routing by setting `{ <> }=true`. - === xref:errors/gql-errors/08N02.adoc[08N02] Status description:: error: connection exception - unable to connect to database. Unable to connect to database `{ <> }`. Server-side routing is disabled. Either connect to `{ $db }` directly, or enable server-side routing by setting `{ <> }=true`. @@ -169,7 +170,7 @@ Status description:: error: data exception - specified negative numeric value. E === xref:errors/gql-errors/22N03.adoc[22N03] -Status description:: error: data exception - specified numeric value out of range. Expected `{ <> }` to be of type `{ <> }` and in the range `{ <> }` to `{ <> }` but found `{ <> }`. +Status description:: error: data exception - specified numeric value out of range. Expected `{ <> }` to be of type `{ <> }` and in the range `{ <> }` to `{ <> }` but found `{ <> }`. === xref:errors/gql-errors/22N04.adoc[22N04] @@ -234,7 +235,7 @@ Status description:: error: data exception - invalid spatial value. A `POINT` mu === xref:errors/gql-errors/22N20.adoc[22N20] -Status description:: error: data exception - invalid spatial value dimensions. Cannot create POINT with `{ <>1D }` coordinate reference system (CRS) and `{ <> }` coordinates. Use the equivalent `{ $dim2D }` coordinate reference system instead. +Status description:: error: data exception - invalid spatial value dimensions. Cannot create POINT with `{ <>1 }D` coordinate reference system (CRS) and `{ <> }` coordinates. Use the equivalent `{ $dim2 }D` coordinate reference system instead. === xref:errors/gql-errors/22N21.adoc[22N21] @@ -270,7 +271,7 @@ Status description:: error: data exception - overflow error. The result of the o === xref:errors/gql-errors/22N29.adoc[22N29] -Status description:: error: data exception - unsupported coordinate reference system. Unknown coordinate reference system (CRS). +Status description:: error: data exception - unknown coordinate reference system. Unknown coordinate reference system (CRS). === xref:errors/gql-errors/22N30.adoc[22N30] @@ -547,15 +548,15 @@ Status description:: error: data exception - invalid property based access contr === xref:errors/gql-errors/22NA4.adoc[22NA4] -Status description:: error: data exception - invalid property based access control rule involving comparison with NULL. The property value access rule pattern `{ <> }` always evaluates to `NULL`. +Status description:: error: data exception - invalid property based access control rule involving comparison with `NULL`. The property value access rule pattern `{ <> }` always evaluates to `NULL`. === xref:errors/gql-errors/22NA5.adoc[22NA5] -Status description:: error: data exception - invalid property based access control rule involving IS NULL. The property value access rule pattern `{ <> }` always evaluates to `NULL`. Use `IS NULL` instead. +Status description:: error: data exception - invalid property based access control rule involving `IS NULL`. The property value access rule pattern `{ <> }` always evaluates to `NULL`. Use `IS NULL` instead. === xref:errors/gql-errors/22NA6.adoc[22NA6] -Status description:: error: data exception - invalid property based access control rule involving IS NOT NULL. The property value access rule pattern `{ <> }` always evaluates to `NULL`. Use `IS NOT NULL` instead. +Status description:: error: data exception - invalid property based access control rule involving `IS NOT NULL`. The property value access rule pattern `{ <> }` always evaluates to `NULL`. Use `IS NOT NULL` instead. === xref:errors/gql-errors/22NA7.adoc[22NA7] @@ -567,11 +568,11 @@ Status description:: error: data exception - parsing JSON failure. Underlying er === xref:errors/gql-errors/22NA9.adoc[22NA9] -Status description:: error: data exception -unexpected map entry. Invalid input. Unexpected key `{ <> }`, expected keys are `{ <> }`. +Status description:: error: data exception - unexpected map entry. Invalid input. Unexpected key `{ <> }`, expected keys are `{ <> }`. === xref:errors/gql-errors/22NB0.adoc[22NB0] -Status description:: error: data exception - invalid property based access control rule involving WHERE and IS NULL. The property value access rule pattern `{ <> }` always evaluates to `NULL`. Use `WHERE` syntax in combination with `IS NULL` instead. +Status description:: error: data exception - invalid property based access control rule involving `WHERE` and `IS NULL`. The property value access rule pattern `{ <> }` always evaluates to `NULL`. Use `WHERE` syntax in combination with `IS NULL` instead. === xref:errors/gql-errors/22NB1.adoc[22NB1] @@ -597,7 +598,6 @@ Status description:: error: data exception - unsupported time zone identifier. U Status description:: error: data exception - input empty. Invalid input. `{ <> }` is not allowed to be an empty string. - === xref:errors/gql-errors/22NB7.adoc[22NB7] Status description:: error: data exception - element id unsupported on composite database. It is not supported to create element ids on composite databases. Create the element id for `{ <> }` `{ <<$entityId>> }` on the constituent instead. @@ -674,6 +674,7 @@ Status description:: error: invalid transaction state - transaction termination Status description:: error: invalid transaction state - transaction termination transient error. The transaction has been terminated. Retry your operation in a new transaction, and you should see a successful result. Reson: `{ <> }` + [[invalid-transaction-termination]] == Invalid transaction termination @@ -708,6 +709,7 @@ Status description:: error: invalid transaction termination - failed to append t Status description:: error: invalid transaction termination - inner transactions still open. Unable to commit transaction because it still have non-closed inner transactions. + [[transaction-rollback]] == Transaction rollback @@ -729,6 +731,7 @@ Status description:: error: transaction rollback - rollback failed. Failed to ro Status description:: error: transaction rollback - constituent rollback failed. Failed to rollback constituent transaction. See debug log for details. + [[syntax-error-or-access-rule-violation]] == Syntax error or access rule violation @@ -808,7 +811,7 @@ Status description:: error: syntax error or access rule violation - invalid inpu === xref:errors/gql-errors/42I07.adoc[42I07] -Status description:: error: syntax error or access rule violation - invalid integer literal. The given `{ <> }` literal `{ <> }` is invalid +Status description:: error: syntax error or access rule violation - invalid integer literal. The given `{ <> }` literal `{ <> }` is invalid. === xref:errors/gql-errors/42I08.adoc[42I08] @@ -1010,7 +1013,7 @@ Status description:: error: syntax error or access rule violation - dynamic enti Status description:: error: syntax error or access rule violation - invalid glob escaping. Each part of the glob (a block of text up until a dot) must either be fully escaped or not escaped at all. -=== xref:errors/gql-errors/42I60.adoc[42I61] +=== xref:errors/gql-errors/42I61.adoc[42I61] Status description:: error: syntax error or access rule violation - missing LOOKUP INDEX function name. Missing function name for the LOOKUP INDEX. @@ -1109,12 +1112,10 @@ Status description:: error: syntax error or access rule violation - duplicate cl Status description:: error: syntax error or access rule violation - empty list range operator. The list range operator `[ ]` cannot be empty. - === xref:errors/gql-errors/42N21.adoc[42N21] Status description:: error: syntax error or access rule violation - unaliased return item. Expression in `{ <> }` must be aliased (use AS). - === xref:errors/gql-errors/42N22.adoc[42N22] Status description:: error: syntax error or access rule violation - single return column required. A `COLLECT` subquery must end with a single return column. @@ -1178,7 +1179,7 @@ Status description:: error: syntax error or access rule violation - incompatible === xref:errors/gql-errors/42N3A.adoc[42N3A] -Status description:: error: syntax error or access rule violation - incompatible conditional query. All `{ <> }` need to either return rows or update the graph. +Status description:: error: syntax error or access rule violation - incompatible conditional query. All `{ <> }` need to either return rows or update the graph. === xref:errors/gql-errors/42N3B.adoc[42N3B] @@ -1188,7 +1189,6 @@ Status description:: error: syntax error or access rule violation - incompatible Status description:: error: syntax error or access rule violation - invalid use of `CALL { ... }`. Not possible to enclose `{ <> }` in `CALL { ... }`. Use `CALL () { ... }` instead. - === xref:errors/gql-errors/42N40.adoc[42N40] Status description:: error: syntax error or access rule violation - single relationship pattern required. The `{ <> }` function must contain one relationship pattern. @@ -1241,12 +1241,10 @@ Status description:: error: syntax error or access rule violation - unsafe usage Status description:: error: syntax error or access rule violation - unsupported match mode. The match mode `{ <> }` is not supported. - === xref:errors/gql-errors/42N56.adoc[42N56] Status description:: error: syntax error or access rule violation - unsupported use of properties. Properties are not supported in the `{ <> }` function. - === xref:errors/gql-errors/42N57.adoc[42N57] Status description:: error: syntax error or access rule violation - invalid use of data-modifications in expressions. `{ <> }` cannot contain any updating clauses. @@ -1301,7 +1299,7 @@ Status description:: error: syntax error or access rule violation - graph functi === xref:errors/gql-errors/42N73.adoc[42N73] -Status description:: error: syntax error or access rule violation - invalid placement of USE clause. The USE clause must be the first clause of a query or an operand to `... UNION ...` . In a CALL sub-query, it can also be the second clause if the first clause is an importing WITH. +Status description:: error: syntax error or access rule violation - invalid placement of `USE` clause. The `USE` clause must be the first clause of a query or an operand to `... UNION ...` . In a `CALL` sub-query, it can also be the second clause if the first clause is an importing `WITH`. === xref:errors/gql-errors/42N74.adoc[42N74] @@ -1375,17 +1373,14 @@ Status description:: error: syntax error or access rule violation - incomplete ` Status description:: error: syntax error or access rule violation - provider-id combination already exists. The combination of provider and id is already in use. - === xref:errors/gql-errors/42N96.adoc[42N96] Status description:: error: syntax error or access rule violation - invalid user configuration. User has no auth provider. Add at least one auth provider for the user or consider suspending them. - === xref:errors/gql-errors/42N97.adoc[42N97] Status description:: error: syntax error or access rule violation - missing mandatory auth clause. Clause `{ <> }` is mandatory for auth provider `{ <> }`. - === xref:errors/gql-errors/42N98.adoc[42N98] Status description:: error: syntax error or access rule violation - cannot modify own user. Cannot modify the user record of the current user. @@ -1450,6 +1445,7 @@ Status description:: error: syntax error or access rule violation - auth info ex Status description:: error: syntax error or access rule violation - permission/access denied. Access denied, see the security logs for details. + [[general-processing-exceptions]] == General processing exceptions @@ -1525,12 +1521,13 @@ Status description:: error: general processing exception - no such schema descri === xref:errors/gql-errors/50N23.adoc[50N23] -error: general processing exception - transaction retry aborted. Transaction retry aborted after `{ <> }` attempts. Retry timed out with a maximum retry duration of `{ <> }` `{ <> }`. +Status description:: error: general processing exception - transaction retry aborted. Transaction retry aborted after `{ <> }` attempts. Retry timed out with a maximum retry duration of `{ <> }` `{ <> }`. === xref:errors/gql-errors/50N42.adoc[50N42] Status description:: error: general processing exception - unexpected error. Unexpected error has occurred. See debug log for details. + [[system-configuration-or-operation-exceptions]] == System configuration or operation exceptions @@ -1540,7 +1537,6 @@ System configuration or operation exception errors occur when there is an error Status description:: error: system configuration or operation exception - procedure registration error. Failed to register procedure/function. - === xref:errors/gql-errors/51N01.adoc[51N01] Status description:: error: system configuration or operation exception - class field annotation should be public, non-final, and non-static. The field `{ <> }` in the class `{ <> }` is annotated as a `@Context` field, but it is declared as static. `@Context` fields must be public, non-final and non-static. @@ -1549,63 +1545,51 @@ Status description:: error: system configuration or operation exception - class Status description:: error: system configuration or operation exception - unsupported injectable component type. Unable to set up injection for procedure `{ <> }`. The field `{ <> }` has type `{ <> }` which is not a supported injectable component. - === xref:errors/gql-errors/51N03.adoc[51N03] Status description:: error: system configuration or operation exception - unable to access field. Unable to set up injection for `{ <> }`, failed to access field `{ <> }`. - === xref:errors/gql-errors/51N04.adoc[51N04] Status description:: error: system configuration or operation exception - missing class field annotation. The field `{ <> }` on `{ <> }` must be annotated as a `@Context` field in order to store its state. - === xref:errors/gql-errors/51N05.adoc[51N05] Status description:: error: system configuration or operation exception - class field should be public and non-final. The field `{ <> }` on `{ <> }` must be declared non-final and public. - === xref:errors/gql-errors/51N06.adoc[51N06] Status description:: error: system configuration or operation exception - missing argument name. The argument at position `{ <> }` in `{ <> }` requires a `@Name` annotation and a non-empty name. - === xref:errors/gql-errors/51N07.adoc[51N07] Status description:: error: system configuration or operation exception - invalid ordering of default arguments. The `{ <> }` contains a non-default argument after a default argument. Non-default arguments are not allowed to be positioned after default arguments. - === xref:errors/gql-errors/51N08.adoc[51N08] Status description:: error: system configuration or operation exception - exactly one @UserAggregationResult method and one @UserAggregationUpdate method required. The class `{ <> }` must contain exactly one `@UserAggregationResult` method and exactly one `@UserAggregationUpdate` method. - === xref:errors/gql-errors/51N09.adoc[51N09] Status description:: error: system configuration or operation exception - @UserAggregationUpdate method must be public and void. The `@UserAggregationUpdate` method `{ <> }` of `{ <> }` must be public and have the return type `void`. - === xref:errors/gql-errors/51N10.adoc[51N10] Status description:: error: system configuration or operation exception - aggregation method not public. The method `{ <> }` of `{ <> }` must be public. - === xref:errors/gql-errors/51N11.adoc[51N11] Status description:: error: system configuration or operation exception - class not public. The class `{ <> }` must be public. - [role=label--changed-2025.03] === xref:errors/gql-errors/51N12.adoc[51N12] Status description:: error: system configuration or operation exception - class not void. The procedure `{ <> }` has zero return columns and must be defined as void. - === xref:errors/gql-errors/51N13.adoc[51N13] Status description:: error: system configuration or operation exception - procedure or function name already in use. Unable to register the procedure or function `{ <> }` because the name is already in use. - === xref:errors/gql-errors/51N14.adoc[51N14] Status description:: error: system configuration or operation exception - duplicate field name. @@ -1615,12 +1599,10 @@ The procedure `{ <> }` has a duplicate `{ <> }` field, `{ < Status description:: error: system configuration or operation exception - invalid map key type. Type mismatch for map key. Required `STRING`, but found `{ <> }`. - === xref:errors/gql-errors/51N16.adoc[51N16] Status description:: error: system configuration or operation exception - invalid default value type. Type mismatch for the default value. Required `{ <> }`, but found `{ <> }`. - === xref:errors/gql-errors/51N17.adoc[51N17] Status description:: error: system configuration or operation exception - invalid procedure or function name. Procedures and functions cannot be defined in the root namespace, or use a reserved namespace. Use the package name instead (e.g., org.example.com.`{ <> }`)`. @@ -1629,7 +1611,6 @@ Status description:: error: system configuration or operation exception - invali Status description:: error: system configuration or operation exception - invalid method return type. The method `{ <> }` has an invalid return type. Procedures must return a stream of records, where each record is of a defined concrete class. - === xref:errors/gql-errors/51N20.adoc[51N20] Status description:: error: system configuration or operation exception - cannot inject field. The field `{ <> }` is not injectable. Ensure the field is marked as public and non-final. @@ -1642,12 +1623,10 @@ Status description:: error: system configuration or operation exception - proced Status description:: error: system configuration or operation exception - exhaustive shortest path search disabled. Finding the shortest path for the given pattern requires an exhaustive search. To enable exhaustive searches, set `cypher.forbid_exhaustive_shortestpath` to false. - === xref:errors/gql-errors/51N23.adoc[51N23] Status description:: error: system configuration or operation exception - cyclic shortest path search disabled. Cannot find the shortest path when the start and end nodes are the same. To enable this behavior, set `dbms.cypher.forbid_shortestpath_common_nodes` to false. - === xref:errors/gql-errors/51N24.adoc[51N24] Status description:: error: system configuration or operation exception - insufficient resources for plan search. Could not find a query plan within given time and space limits. @@ -1656,7 +1635,6 @@ Status description:: error: system configuration or operation exception - insuff Status description:: error: system configuration or operation exception - database is busy. Cannot compile query due to excessive updates to indexes and constraints. - === xref:errors/gql-errors/51N26.adoc[51N26] Status description:: error: system configuration or operation exception - not supported in this version. `{ <> }` is not available. This implementation of Cypher does not support `{ <> }`. @@ -1670,37 +1648,30 @@ Status description:: error: system configuration or operation exception - not su Status description:: error: system configuration or operation exception - not supported by this database. This Cypher command must be executed against the database `{ <> }`. - === xref:errors/gql-errors/51N29.adoc[51N29] Status description:: error: system configuration or operation exception - not supported by this server. The command `{ <> }` must be executed on the current `LEADER` server. - === xref:errors/gql-errors/51N30.adoc[51N30] Status description:: error: system configuration or operation exception - not supported with this configuration. `{ <> }` is not supported in `{ <> }`. - === xref:errors/gql-errors/51N31.adoc[51N31] Status description:: error: system configuration or operation exception - not supported. `{ <> }` is not supported in `{ <> }`. - === xref:errors/gql-errors/51N32.adoc[51N32] Status description:: error: system configuration or operation exception - server panic. Server is in panic. - === xref:errors/gql-errors/51N33.adoc[51N33] Status description:: error: system configuration or operation exception - replication error. This member failed to replicate transaction, try again. - === xref:errors/gql-errors/51N34.adoc[51N34] Status description:: error: system configuration or operation exception - write transaction failed due to leader change. Failed to write to the database due to a cluster leader change. Retrying your request at a later time may succeed. - === xref:errors/gql-errors/51N35.adoc[51N35] Status description:: error: system configuration or operation exception - database location changed. The location of `{ <> }` has changed while the transaction was running. @@ -1721,67 +1692,54 @@ Status description:: error: system configuration or operation exception - failed Status description:: error: system configuration or operation exception - raft log corrupted. Expected set of files not found on disk. Please restore from backup. - === xref:errors/gql-errors/51N40.adoc[51N40] Status description:: error: system configuration or operation exception - unable to start database. Database `{ <> }` failed to start. Try restarting it. - === xref:errors/gql-errors/51N41.adoc[51N41] Status description:: error: system configuration or operation exception - admin operation failed. Server or database admin operation not possible. - === xref:errors/gql-errors/51N43.adoc[51N43] Status description:: error: system configuration or operation exception - cannot deallocate servers. Cannot deallocate server(s) `{ <> }`. - === xref:errors/gql-errors/51N44.adoc[51N44] Status description:: error: system configuration or operation exception - cannot drop server. Cannot drop server `{ <> }`. - === xref:errors/gql-errors/51N45.adoc[51N45] Status description:: error: system configuration or operation exception - cannot cordon server. Cannot cordon server `{ <> }`. - === xref:errors/gql-errors/51N46.adoc[51N46] Status description:: error: system configuration or operation exception - cannot alter server. Cannot alter server `{ <> }`. - === xref:errors/gql-errors/51N47.adoc[51N47] Status description:: error: system configuration or operation exception - cannot rename server. Cannot rename server `{ <> }`. - === xref:errors/gql-errors/51N48.adoc[51N48] Status description:: error: system configuration or operation exception - cannot enable server. Cannot enable server `{ <> }`. - === xref:errors/gql-errors/51N49.adoc[51N49] Status description:: error: system configuration or operation exception - cannot alter database. Cannot alter database `{ <> }`. - === xref:errors/gql-errors/51N50.adoc[51N50] Status description:: error: system configuration or operation exception - cannot recreate database. Cannot recreate database `{ <> }`. - === xref:errors/gql-errors/51N51.adoc[51N51] Status description:: error: system configuration or operation exception - cannot create database. Cannot create database `{ <> }`. - === xref:errors/gql-errors/51N52.adoc[51N52] Status description:: error: system configuration or operation exception - number of primaries out of range. Cannot alter database topology. Number of primaries `{ <> }` needs to be at least 1 and may not exceed `{ <> }`. - === xref:errors/gql-errors/51N53.adoc[51N53] Status description:: error: system configuration or operation exception - number of secondaries out of range. Cannot alter database topology. Number of secondaries `{ <> }` needs to be at least 0 and may not exceed `{ <> }`. @@ -1790,7 +1748,6 @@ Status description:: error: system configuration or operation exception - number Status description:: error: system configuration or operation exception - cannot reallocate. Failed to calculate reallocation for databases. `{ <> }` - === xref:errors/gql-errors/51N55.adoc[51N55] Status description:: error: system configuration or operation exception - cannot create additional database. Failed to create the database `{ <> }`. The limit of databases is reached. Either increase the limit using the config setting `{ <> }` or drop a database. @@ -1799,16 +1756,13 @@ Status description:: error: system configuration or operation exception - cannot Status description:: error: system configuration or operation exception - topology out of range. The number of `{ <> }` seeding servers `{ <>1 }` is larger than the desired number of `{ <> }` allocations `{ $count2 }`. - === xref:errors/gql-errors/51N57.adoc[51N57] Status description:: error: system configuration or operation exception - generic topology modification error. Unexpected error while picking allocations. `{ <> }` - === xref:errors/gql-errors/51N58.adoc[51N58] -Status description:: error: system configuration or operation exception - invalid shard topology. Invalid database shard topology. The number of `{ <> }` `{ <<$count>> }` needs to be at least 1 and may not exceed `{ <> }`. - +Status description:: error: system configuration or operation exception - invalid shard topology. Invalid database shard topology. The number of `{ <> }` `{ <> }` needs to be at least 1 and may not exceed `{ <> }`. === xref:errors/gql-errors/51N59.adoc[51N59] @@ -1830,16 +1784,13 @@ Status description:: error: system configuration or operation exception - index Status description:: error: system configuration or operation exception - index is still populating. Index is not ready yet. Wait until it finishes populating and retry the transaction. - === xref:errors/gql-errors/51N64.adoc[51N64] Status description:: error: system configuration or operation exception - index dropped while sampling. The index dropped while sampling. - === xref:errors/gql-errors/51N65.adoc[51N65] -Status description:: error: system configuration or operation exception - vector index dimensionality mismatch. Vector index `{ <> }` has a dimensionality of `{ <>1 }`, but indexed vectors have `{ $dim2}`. - +Status description:: error: system configuration or operation exception - vector index dimensionality mismatch. Vector index `{ <> }` has a dimensionality of `{ <>1 }`, but indexed vectors have `{ $dim2 }`. === xref:errors/gql-errors/51N66.adoc[51N66] @@ -1877,6 +1828,7 @@ Status description:: error: system configuration or operation exception - transa Status description:: error: system configuration or operation exception - maximum number of transactions reached. Failed to start a new transaction. The limit of concurrent transactions is reached. Increase the number of concurrent transactions using `{ <> }` in the neo4j.conf file. + [[procedure-exceptions]] == Procedure exceptions @@ -2030,6 +1982,7 @@ Status description:: error: procedure exception - cdc scanner inactive. The log Status description:: error: procedure exception - custom procedure execution error cause. Execution of the procedure `{ <> }` failed due to `{ <> }`: `{ <> }` + [[function-exceptions]] == Function exceptions @@ -2049,8 +2002,9 @@ Status description:: error: function exception - function execution error. Execu Status description:: error: function exception - custom function execution error cause. Execution of the function `{ <> }` failed due to `{ <> }`: `{ <> }`. -[[dependent-object-error]] -== Dependent object error + +[[dependent-object-errors]] +== Dependent object errors === xref:errors/gql-errors/G1001.adoc[G1001] diff --git a/modules/ROOT/templates/gql-index-template.adoc b/modules/ROOT/templates/gql-index-template.adoc new file mode 100644 index 00000000..8f56ab2c --- /dev/null +++ b/modules/ROOT/templates/gql-index-template.adoc @@ -0,0 +1,96 @@ + + +:description: This section describes the GQLSTATUS errors that Neo4j can return, grouped by category, and an example of when they can occur. + +[[neo4j-gqlstatus-errors]] += List of GQLSTATUS error codes + +The following page provides an overview of all GQLSTATUS server error codes in Neo4j. +All errors in Neo4j have severity level `ERROR`. + +[WARNING] +==== +Please note that while GQLSTATUS codes remain stable (any changes to them will be breaking), changes to status descriptions associated with these codes are not breaking and may happen at any time. +For this reason, parsing the status descriptions or incorporating them into scripts is not recommended. +==== + +[[connection-exceptions]] +== Connection exceptions + +Connection exceptions occur when the client (e.g. Browser/Bloom/Cypher Shell) is unable to connect to the server for various reasons such as network issues, server-side routing being disabled, or the database being unavailable, etc. + +{codes_starting_with:'08'} + +[[data-exceptions]] +== Data exceptions + +Database exceptions occur when a client request contains the wrong format, types, or other unsupported input. +Some examples are data and constraint creation, which conflicts with existing constraints, properties of non-storable type, and spatial and temporal values with invalid components. + +{codes_starting_with:'22'} + +[[invalid-transaction-state]] +== Invalid transaction state + +Invalid transaction state errors occur when the transaction is in an invalid state, such as when the transaction is terminated or closed, or when there is a conflict between the transaction state and applied updates. + +{codes-starting with: '25'} + +[[invalid-transaction-termination]] +== Invalid transaction termination + +Invalid transaction termination errors occur when the transaction termination fails, such as when the transaction or constituent transaction fails to commit, or when the transaction termination fails to apply or append the transaction. + +{codes-starting with: '2D'} + +[[transaction-rollback]] +== Transaction rollback + +Transaction rollback errors occur when there is a failure in a transaction or a constituent transaction rollback. + +{codes-starting with: '40'} + +[[syntax-error-or-access-rule-violation]] +== Syntax error or access rule violation + +Syntax error or access rule violation errors occur when a Cypher query contains invalid syntax or when a client request violates the access rules, such as when a query tries to access a database without enough privileges, etc. + +{codes-starting with: '42'} + +[[general-processing-exceptions]] +== General processing exceptions + +General processing exceptions occur when there is a general processing error, such as an internal error, deadlock, execution failure, invalid server state transition, constraint creation or drop failure, etc. + +{codes-starting with: '50'} + +[[system-configuration-or-operation-exceptions]] +== System configuration or operation exceptions + +System configuration or operation exception errors occur when there is an error in the system configuration or operation, such as procedure registration failure, a missing class field annotation, an unsupported injectable component type, duplicate field names, invalid map key type, etc. + +{codes-starting with: '51'} + +[[procedure-exceptions]] +== Procedure exceptions + +Procedure exceptions occur when there is an error in executing a procedure, such as when the procedure execution fails due to a client error, when the procedure cannot be invoked on a primary, when the number of arguments to checkConnectivity is invalid, etc. + +{codes-starting with: '52'} + +[[function-exceptions]] +== Function exceptions + +{codes-starting with: '53'} + +[[dependent-object-errors]] +== Dependent object errors + +{codes-starting with: 'G1'} + +ifndef::backend-pdf[] +[discrete.glossary] +== Glossary + +include::partial$glossary.adoc[] +endif::[] diff --git a/scripts/README.adoc b/scripts/README.adoc new file mode 100644 index 00000000..10fbdf02 --- /dev/null +++ b/scripts/README.adoc @@ -0,0 +1,48 @@ += Scripts for generating and validating gql error index.adoc file + +This folder contains utility scripts for generating and validating gql error index.adoc file. + +== Scripts overview + +The folder contains the following scripts: + + +=== `generate-gql-error-index-from-template.py` + +This script generates the _auto-index.adoc_ file by using the template in _templates/gql-index-template.adoc_ and populating it with error codes from the individual files located in the _gql-errors_ directory. + +What it does:: +* Extracts error codes from filenames (e.g., 42007.adoc → 42007). +* Extracts the status descriptions from individual error files. +* Extracts page roles from files (`:page-role: changed-2025.04`). +* Creates a new _auto-index.adoc_ file based on the template and populates it with the extracted data. + +=== `validate-error-index.py` + +This index validates the consistency between _index.adoc_ and individual error files, identifying discrepancies in error codes, status descriptions, and page roles. + +What it does:: +* Checks for error codes mentioned in the index.adoc file that don't have corresponding files. +* Finds error files without index entries. +* Detects status description mismatches between the index and individual files. +* Verifies page role consistency. + +=== `validate-error-auto-index.py` + +This index validates the consistency between _auto-index.adoc_ and individual error files, identifying discrepancies in error codes, status descriptions, and page roles. + +What it does:: +* Checks for error codes mentioned in the index.adoc file that don't have corresponding files. +* Finds error files without index entries. +* Detects status description mismatches between the index and individual files. +* Verifies page role consistency. + +=== `update-gql-error-index.sh` +This script orchestrates the execution of the other scripts in a specific order to ensure that the error index is generated and validated correctly. + +What it does:: +1. Runs the validation script to check for discrepancies between the _index.adoc_ file and the individual error files. +2. If validation passes, it runs the generation script to create the _auto-index.adoc_ file. +3. Runs the validation script again to check for discrepancies between the _auto-index.adoc_ file and the individual error files. +4. If validation passes, it replaces the existing _index.adoc_ file with _auto-index.adoc_. +5. If validation fails, it prints an error message and does not replace the _index.adoc_ file, while also keeping the _auto-index.adoc_ file for manual review. \ No newline at end of file diff --git a/scripts/generate-gql-error-index-from-template.py b/scripts/generate-gql-error-index-from-template.py new file mode 100644 index 00000000..4cae2ade --- /dev/null +++ b/scripts/generate-gql-error-index-from-template.py @@ -0,0 +1,185 @@ +#!/usr/bin/env python3 + +import os +import re +from pathlib import Path +import argparse + +# For debugging - examine a single file to understand its structure +def examine_error_file(file_path): + """Print the contents of an error file for debugging.""" + try: + with open(file_path, 'r') as f: + content = f.read() + print(f"=== File Content for {file_path.name} ===") + print(content) + print("===================================") + + # Try to extract the description with different patterns + patterns = [ + r'Status description::\s*(.*?)(?=\n\n|\n==|\Z)', + r'== Status description\s*\n(.*?)(?=\n\n|\n==|\Z)', + r'== Status description\s*\n\s*Status description:: (.*?)(?=\n\n|\n==|\Z)' + ] + + for i, pattern in enumerate(patterns): + match = re.search(pattern, content, re.DOTALL) + if match: + print(f"Pattern {i+1} matched! Description: {match.group(1)[:50]}...") + else: + print(f"Pattern {i+1} did not match") + except Exception as e: + print(f"Error reading file: {e}") + +def get_error_codes_from_files(errors_dir, verbose=False): + """Get all error codes and their details from individual .adoc files.""" + error_codes = {} + sample_file = None + + for file in os.listdir(errors_dir): + if file.endswith('.adoc') and file != 'index.adoc' and file != 'auto-index.adoc': + error_code = file[:-5] # Remove .adoc extension + file_path = os.path.join(errors_dir, file) + + if sample_file is None: + sample_file = file_path # Save first file for debugging + + # Extract details from file + with open(file_path, 'r') as f: + content = f.read() + + # Extract page role + page_role = None + role_match = re.search(r':page-role:\s*(.*?)(?=\n|\Z)', content) + if role_match: + page_role = role_match.group(1).strip() + + # Extract description - try several patterns + description = None + desc_patterns = [ + r'Status description::\s*(.*?)(?=\n\n|\n==|\Z)', # Simple format + r'== Status description\s*\n\s*Status description:: (.*?)(?=\n\n|\n==|\Z)', # Section + desc + r'== Status description\s*\n(.*?)(?=\n\n|\n==|\Z)' # Section only + ] + + for pattern in desc_patterns: + match = re.search(pattern, content, re.DOTALL) + if match: + description = match.group(1).strip() + break + + error_codes[error_code] = { + 'description': description, + 'page_role': page_role + } + + if verbose and description: + print(f"Found description for {error_code}: {description[:50]}...") + elif verbose: + print(f"No description found for {error_code}") + + # If we didn't find any descriptions, examine a sample file + if verbose and sample_file and not any(code['description'] for code in error_codes.values()): + print("\nNo descriptions were found in any files. Examining a sample file:") + examine_error_file(sample_file) + + return error_codes + +def generate_from_template(template_file, errors_dir, output_file, include_descriptions=True, verbose=False): + """Generate the index file from template and individual error files.""" + if verbose: + print("Extracting error codes and descriptions...") + + # Get error codes and their info with improved extraction + error_codes = get_error_codes_from_files(errors_dir, verbose) + + if verbose: + desc_count = sum(1 for code in error_codes.values() if code['description']) + print(f"Found {len(error_codes)} error code files, {desc_count} with descriptions") + + # Read the template + with open(template_file, 'r') as f: + template_content = f.read() + + # Define patterns to find placeholders + patterns = [ + r'\{codes_starting_with:\'([^\']+)\'\}', + r'\{codes-starting with: \'([^\']+)\'\}' + ] + + # Replace placeholders with generated content + for pattern in patterns: + for match in re.finditer(pattern, template_content): + prefix = match.group(1) + placeholder = match.group(0) + + if verbose: + print(f"Processing prefix: {prefix}") + + # Generate content for this prefix + content = [] + matching_codes = [code for code in sorted(error_codes.keys()) if code.startswith(prefix)] + + for error_code in matching_codes: + # Add page role if exists + if error_codes[error_code]['page_role']: + content.append(f'[role=label--{error_codes[error_code]["page_role"]}]') + + content.append(f'=== xref:errors/gql-errors/{error_code}.adoc[{error_code}]') + content.append('') + + # Add description if available and requested + if include_descriptions and error_codes[error_code]['description']: + content.append(f'Status description:: {error_codes[error_code]["description"]}') + content.append('') + + section_content = '\n'.join(content) + + # Replace placeholder with generated content + template_content = template_content.replace(placeholder, section_content) + + # Write the result to the output file + with open(output_file, 'w') as f: + f.write("// This is an automatically generated file. Do not edit it directly. It is generated from the templates/gql-index-template.adoc file and should be edited there.\n") + f.write(template_content) + + print(f'Generated index file at: {output_file}') + print(f'Used template: {template_file}') + print(f'Total error codes processed: {len(error_codes)}') + +def main(): + # Set up argument parser + parser = argparse.ArgumentParser(description='Generate GraphQL error code index from template') + parser.add_argument('--no-descriptions', action='store_true', + help='If set, only error codes will be listed without their descriptions') + parser.add_argument('--verbose', action='store_true', + help='Show detailed information during processing') + parser.add_argument('--debug-file', help='Debug a specific error file') + args = parser.parse_args() + + # Get the script's directory + script_dir = Path(__file__).parent.absolute() + + # Navigate to the required directories + errors_dir = script_dir.parent / 'modules' / 'ROOT' / 'pages' / 'errors' / 'gql-errors' + template_file = script_dir.parent / 'modules' / 'ROOT' / 'templates' / 'gql-index-template.adoc' + output_file = errors_dir / 'auto-index.adoc' + + # Debug specific file if requested + if args.debug_file: + debug_path = errors_dir / f"{args.debug_file}.adoc" + if debug_path.exists(): + examine_error_file(debug_path) + else: + print(f"Error: Debug file not found at {debug_path}") + return + + if not template_file.exists(): + print(f"Error: Template file not found at {template_file}") + return + + generate_from_template(template_file, errors_dir, output_file, + not args.no_descriptions, args.verbose) + +if __name__ == '__main__': + main() \ No newline at end of file diff --git a/scripts/update-gql-error-index.py b/scripts/update-gql-error-index.py new file mode 100755 index 00000000..42819f7e --- /dev/null +++ b/scripts/update-gql-error-index.py @@ -0,0 +1,62 @@ +#!/usr/bin/env python3 + +import os +import subprocess +import shutil + +# Define paths +script_dir = os.path.dirname(os.path.abspath(__file__)) +project_root = os.path.dirname(script_dir) +errors_dir = os.path.join(project_root, "modules", "ROOT", "pages", "errors", "gql-errors") +index_file = os.path.join(errors_dir, "index.adoc") +auto_index_file = os.path.join(errors_dir, "auto-index.adoc") + +def run_python_script(script_name): + """Run a Python script and return its exit code""" + script_path = os.path.join(script_dir, script_name) + result = subprocess.run(["python3", script_path], capture_output=True, text=True) + print(result.stdout) + return result.returncode + +# Main workflow +def main(): + print("===== Starting GQL Error Index Update Process =====") + + # Step 1: Validate index.adoc + print("Step 1: Validating index.adoc against individual files...") + validation_result = run_python_script("validate-error-index.py") + + # Step 2: Check validation result + if validation_result == 0: + print("✅ Validation passed! No further action needed.") + return 0 + + # Step 3: Generate auto-index.adoc + print("Step 3: Generating auto-index.adoc from template...") + generation_result = run_python_script("generate-gql-error-index-from-template.py") + + if generation_result != 0 or not os.path.exists(auto_index_file): + print("Error: Failed to generate auto-index.adoc") + return 1 + + # Step 4: Validate auto-index.adoc + print("Step 4: Validating auto-index.adoc against individual files...") + auto_validation_result = run_python_script("validate-error-auto-index.py") + + # Step 5: If auto-index validation passes, replace index.adoc + if auto_validation_result == 0: + print("Step 5: Auto-index validation passed! Replacing index.adoc...") + + # Replace index with auto-index + os.remove(index_file) + os.rename(auto_index_file, index_file) + + print("✅ Update completed successfully.") + return 0 + else: + print("❌ Auto-index validation failed.") + print("No changes were made to index.adoc.") + return auto_validation_result + +if __name__ == "__main__": + exit(main()) \ No newline at end of file diff --git a/scripts/validate-error-auto-index.py b/scripts/validate-error-auto-index.py new file mode 100644 index 00000000..a91be7cd --- /dev/null +++ b/scripts/validate-error-auto-index.py @@ -0,0 +1,257 @@ +#!/usr/bin/env python3 + +import os +import re +from pathlib import Path +import argparse +import sys +from difflib import ndiff + +def get_error_codes_from_index(index_file): + """Extract error codes and their descriptions from the index file.""" + error_codes = {} + + try: + with open(index_file, 'r') as f: + content = f.read() + + # Find all error code entries with descriptions + pattern = r'=== xref:errors/gql-errors/([A-Z0-9]{5})\.adoc\[\1\]\s*\n\s*\n\s*Status description:: (.*?)(?=\n\s*\n|\n===|\Z)' + matches = re.findall(pattern, content, re.DOTALL) + + for code, desc in matches: + error_codes[code] = desc.strip() + + return error_codes + except Exception as e: + print(f"Error reading index file {index_file}: {e}") + return {} + +def get_page_roles_from_index(index_file): + """Extract page roles for error codes from the index file.""" + roles = {} + + try: + with open(index_file, 'r') as f: + lines = f.readlines() + + for i, line in enumerate(lines): + role_match = re.search(r'\[role=label--([^\]]+)\]', line) + if role_match and i + 1 < len(lines): + code_match = re.search(r'xref:errors/gql-errors/([A-Z0-9]{5})\.adoc', lines[i+1]) + if code_match: + roles[code_match.group(1)] = role_match.group(1) + + return roles + except Exception as e: + print(f"Error reading index file for roles {index_file}: {e}") + return {} + +def get_error_codes_from_files(errors_dir): + """Get error codes and descriptions from individual error files.""" + error_codes = {} + + try: + for file in os.listdir(errors_dir): + if file.endswith('.adoc') and file != 'index.adoc' and file != 'auto-index.adoc': + error_code = file[:-5] # Remove .adoc extension + file_path = os.path.join(errors_dir, file) + + # Extract description from file + description = extract_description_from_file(file_path) + + if description: + error_codes[error_code] = description + else: + error_codes[error_code] = None + + return error_codes + except Exception as e: + print(f"Error scanning error files directory {errors_dir}: {e}") + return {} + +def extract_description_from_file(file_path): + """Extract the status description from an error file.""" + try: + with open(file_path, 'r') as f: + content = f.read() + + # Try different patterns to match the description + patterns = [ + r'== Status description\s*\n(.*?)(?=\n\n|\n==|\Z)', # Format with standalone line + r'Status description::\s*(.*?)(?=\n\n|\n==|\Z)' # Format with Status description:: prefix + ] + + for pattern in patterns: + match = re.search(pattern, content, re.DOTALL) + if match: + description = match.group(1).strip() + if description.startswith('Status description::'): + description = description[len('Status description::'):].strip() + return description + + return None + except Exception as e: + print(f"Error reading file {file_path}: {e}") + return None + +def get_page_roles_from_files(errors_dir): + """Get page roles from individual error files.""" + roles = {} + + try: + for file in os.listdir(errors_dir): + if file.endswith('.adoc') and file != 'index.adoc' and file != 'auto-index.adoc': + error_code = file[:-5] # Remove .adoc extension + file_path = os.path.join(errors_dir, file) + + # Extract page role from file + with open(file_path, 'r') as f: + for line in f: + if line.strip().startswith(':page-role:'): + roles[error_code] = line.strip()[11:].strip() + break + + return roles + except Exception as e: + print(f"Error scanning error files for roles {errors_dir}: {e}") + return {} + +def format_description(desc, max_len=60): + """Format a description for display, truncating if necessary.""" + if not desc: + return "MISSING" + if len(desc) > max_len: + return f"{desc[:max_len]}..." + return desc + +def validate_error_parity(errors_dir, auto_index_file, verbose=False): + """Validate error code parity between auto-index and individual files.""" + # Get error codes from auto-index and files + auto_index_codes = get_error_codes_from_index(auto_index_file) + file_codes = get_error_codes_from_files(errors_dir) + + # Get page roles + auto_index_roles = get_page_roles_from_index(auto_index_file) + file_roles = get_page_roles_from_files(errors_dir) + + # Find missing files and entries + codes_in_auto_index_not_in_files = set(auto_index_codes.keys()) - set(file_codes.keys()) + codes_in_files_not_in_auto_index = set(file_codes.keys()) - set(auto_index_codes.keys()) + + # Find description mismatches + description_mismatches = [] + for code in set(auto_index_codes.keys()) & set(file_codes.keys()): + auto_index_desc = auto_index_codes[code] if code in auto_index_codes else None + file_desc = file_codes[code] if code in file_codes else None + + # If file has no description, this isn't a mismatch, just incomplete documentation + if file_desc is None: + continue + + # Compare normalized descriptions (strip whitespace and standardize spacing) + if auto_index_desc and file_desc: + auto_index_desc_norm = re.sub(r'\s+', ' ', auto_index_desc.strip()) + file_desc_norm = re.sub(r'\s+', ' ', file_desc.strip()) + + if auto_index_desc_norm != file_desc_norm: + description_mismatches.append((code, auto_index_desc, file_desc)) + + # Find role mismatches + role_mismatches = [] + for code in set(auto_index_roles.keys()) | set(file_roles.keys()): + auto_index_role = auto_index_roles.get(code) + file_role = file_roles.get(code) + + if auto_index_role != file_role: + role_mismatches.append((code, auto_index_role, file_role)) + + # Print results + print(f"\n=== Auto-Index Validation Results ===\n") + print(f"Total error codes in auto-index: {len(auto_index_codes)}") + print(f"Total error code files: {len(file_codes)}") + + # Missing files + if codes_in_auto_index_not_in_files: + print(f"\n{len(codes_in_auto_index_not_in_files)} error codes in auto-index but missing files:") + for code in sorted(codes_in_auto_index_not_in_files): + print(f" - {code}: {format_description(auto_index_codes.get(code))}") + else: + print("\nNo error codes are missing files. ✓") + + # Missing entries + if codes_in_files_not_in_auto_index: + print(f"\n{len(codes_in_files_not_in_auto_index)} error files without auto-index entries:") + for code in sorted(codes_in_files_not_in_auto_index): + print(f" - {code}: {format_description(file_codes.get(code))}") + else: + print("\nNo error files are missing from the auto-index. ✓") + + # Description mismatches + if description_mismatches: + print(f"\n{len(description_mismatches)} description mismatches:") + for code, auto_index_desc, file_desc in sorted(description_mismatches): + print(f"\n - {code}:") + print(f" Auto-Index: {format_description(auto_index_desc)}") + print(f" File : {format_description(file_desc)}") + + if verbose: + # Show exact differences for detailed debugging + print("\n Detailed differences:") + differences = list(ndiff(auto_index_desc.splitlines(), file_desc.splitlines())) + for line in differences: + if line.startswith('+ ') or line.startswith('- ') or line.startswith('? '): + print(f" {line}") + else: + print("\nNo description mismatches found. ✓") + + # Role mismatches + if role_mismatches: + print(f"\n{len(role_mismatches)} page role mismatches:") + for code, auto_index_role, file_role in sorted(role_mismatches): + print(f" - {code}:") + print(f" Auto-Index: {auto_index_role or 'MISSING'}") + print(f" File : {file_role or 'MISSING'}") + else: + print("\nNo page role mismatches found. ✓") + + # Final status + if not (codes_in_auto_index_not_in_files or codes_in_files_not_in_auto_index or + description_mismatches or role_mismatches): + print("\n✅ All validations passed! Auto-index is consistent with individual files.") + return True + else: + print("\n❌ Validation failed.") + return False + +def main(): + parser = argparse.ArgumentParser(description='Validate auto-index.adoc against individual error files') + parser.add_argument('--auto-index', help='Path to auto-index.adoc file') + parser.add_argument('--dir', help='Path to directory containing error files') + parser.add_argument('--verbose', '-v', action='store_true', help='Show detailed differences for mismatches') + args = parser.parse_args() + + # Get the script's directory + script_dir = Path(__file__).parent.absolute() + + # Default paths if not specified + errors_dir = args.dir if args.dir else script_dir.parent / 'modules' / 'ROOT' / 'pages' / 'errors' / 'gql-errors' + auto_index_file = args.auto_index if args.auto_index else errors_dir / 'auto-index.adoc' + + # Validate that the paths exist + if not os.path.exists(errors_dir): + print(f"Error: Directory not found: {errors_dir}") + return 1 + + if not os.path.exists(auto_index_file): + print(f"Error: Auto-index file not found: {auto_index_file}") + return 1 + + # Run validation + success = validate_error_parity(errors_dir, auto_index_file, args.verbose) + + # Return 0 if success, 1 otherwise + return 0 if success else 1 + +if __name__ == '__main__': + sys.exit(main()) \ No newline at end of file diff --git a/scripts/validate-error-index.py b/scripts/validate-error-index.py new file mode 100755 index 00000000..de7bb6e9 --- /dev/null +++ b/scripts/validate-error-index.py @@ -0,0 +1,257 @@ +#!/usr/bin/env python3 + +import os +import re +from pathlib import Path +import argparse +import sys + +def get_error_codes_from_index(index_file): + """Extract error codes and their descriptions from the index file.""" + error_codes = {} + + try: + with open(index_file, 'r') as f: + content = f.read() + + # Find all error code entries with descriptions + pattern = r'=== xref:errors/gql-errors/([A-Z0-9]{5})\.adoc\[\1\]\s*\n\s*\n\s*Status description:: (.*?)(?=\n\s*\n|\n===|\Z)' + matches = re.findall(pattern, content, re.DOTALL) + + for code, desc in matches: + error_codes[code] = desc.strip() + + return error_codes + except Exception as e: + print(f"Error reading index file {index_file}: {e}") + return {} + +def get_page_roles_from_index(index_file): + """Extract page roles for error codes from the index file.""" + roles = {} + + try: + with open(index_file, 'r') as f: + lines = f.readlines() + + for i, line in enumerate(lines): + role_match = re.search(r'\[role=label--([^\]]+)\]', line) + if role_match and i + 1 < len(lines): + code_match = re.search(r'xref:errors/gql-errors/([A-Z0-9]{5})\.adoc', lines[i+1]) + if code_match: + roles[code_match.group(1)] = role_match.group(1) + + return roles + except Exception as e: + print(f"Error reading index file for roles {index_file}: {e}") + return {} + +def get_error_codes_from_files(errors_dir): + """Get error codes and descriptions from individual error files.""" + error_codes = {} + + try: + for file in os.listdir(errors_dir): + if file.endswith('.adoc') and file != 'index.adoc' and file != 'auto-index.adoc': + error_code = file[:-5] # Remove .adoc extension + file_path = os.path.join(errors_dir, file) + + # Extract description from file + description = extract_description_from_file(file_path) + + if description: + error_codes[error_code] = description + else: + error_codes[error_code] = None + + return error_codes + except Exception as e: + print(f"Error scanning error files directory {errors_dir}: {e}") + return {} + +def extract_description_from_file(file_path): + """Extract the status description from an error file.""" + try: + with open(file_path, 'r') as f: + content = f.read() + + # Try different patterns to match the description + patterns = [ + r'== Status description\s*\n(.*?)(?=\n\n|\n==|\Z)', # Format with standalone line + r'Status description::\s*(.*?)(?=\n\n|\n==|\Z)' # Format with Status description:: prefix + ] + + for pattern in patterns: + match = re.search(pattern, content, re.DOTALL) + if match: + description = match.group(1).strip() + if description.startswith('Status description::'): + description = description[len('Status description::'):].strip() + return description + + return None + except Exception as e: + print(f"Error reading file {file_path}: {e}") + return None + +def get_page_roles_from_files(errors_dir): + """Get page roles from individual error files.""" + roles = {} + + try: + for file in os.listdir(errors_dir): + if file.endswith('.adoc') and file != 'index.adoc' and file != 'auto-index.adoc': + error_code = file[:-5] # Remove .adoc extension + file_path = os.path.join(errors_dir, file) + + # Extract page role from file + with open(file_path, 'r') as f: + for line in f: + if line.strip().startswith(':page-role:'): + roles[error_code] = line.strip()[11:].strip() + break + + return roles + except Exception as e: + print(f"Error scanning error files for roles {errors_dir}: {e}") + return {} + +def format_description(desc, max_len=60): + """Format a description for display, truncating if necessary.""" + if not desc: + return "MISSING" + if len(desc) > max_len: + return f"{desc[:max_len]}..." + return desc + +def validate_error_parity(errors_dir, index_file, verbose=False): + """Validate error code parity between index and individual files.""" + # Get error codes from index and files + index_codes = get_error_codes_from_index(index_file) + file_codes = get_error_codes_from_files(errors_dir) + + # Get page roles + index_roles = get_page_roles_from_index(index_file) + file_roles = get_page_roles_from_files(errors_dir) + + # Find missing files and entries + codes_in_index_not_in_files = set(index_codes.keys()) - set(file_codes.keys()) + codes_in_files_not_in_index = set(file_codes.keys()) - set(index_codes.keys()) + + # Find description mismatches + description_mismatches = [] + for code in set(index_codes.keys()) & set(file_codes.keys()): + index_desc = index_codes[code] if code in index_codes else None + file_desc = file_codes[code] if code in file_codes else None + + # If file has no description, this isn't a mismatch, just incomplete documentation + if file_desc is None: + continue + + # Compare normalized descriptions (strip whitespace and standardize spacing) + if index_desc and file_desc: + index_desc_norm = re.sub(r'\s+', ' ', index_desc.strip()) + file_desc_norm = re.sub(r'\s+', ' ', file_desc.strip()) + + if index_desc_norm != file_desc_norm: + description_mismatches.append((code, index_desc, file_desc)) + + # Find role mismatches + role_mismatches = [] + for code in set(index_roles.keys()) | set(file_roles.keys()): + index_role = index_roles.get(code) + file_role = file_roles.get(code) + + if index_role != file_role: + role_mismatches.append((code, index_role, file_role)) + + # Print results + print(f"\n=== Error Code Parity Validation Results ===\n") + print(f"Total error codes in index: {len(index_codes)}") + print(f"Total error code files: {len(file_codes)}") + + # Missing files + if codes_in_index_not_in_files: + print(f"\n{len(codes_in_index_not_in_files)} error codes in index but missing files:") + for code in sorted(codes_in_index_not_in_files): + print(f" - {code}: {format_description(index_codes.get(code))}") + else: + print("\nNo error codes are missing files. ✓") + + # Missing entries + if codes_in_files_not_in_index: + print(f"\n{len(codes_in_files_not_in_index)} error files without index entries:") + for code in sorted(codes_in_files_not_in_index): + print(f" - {code}: {format_description(file_codes.get(code))}") + else: + print("\nNo error files are missing from the index. ✓") + + # Description mismatches + if description_mismatches: + print(f"\n{len(description_mismatches)} description mismatches:") + for code, index_desc, file_desc in sorted(description_mismatches): + print(f"\n - {code}:") + print(f" Index: {format_description(index_desc)}") + print(f" File : {format_description(file_desc)}") + + if verbose: + # Show exact differences for detailed debugging + from difflib import ndiff + print("\n Detailed differences:") + differences = list(ndiff(index_desc.splitlines(), file_desc.splitlines())) + for line in differences: + if line.startswith('+ ') or line.startswith('- ') or line.startswith('? '): + print(f" {line}") + else: + print("\nNo description mismatches found. ✓") + + # Role mismatches + if role_mismatches: + print(f"\n{len(role_mismatches)} page role mismatches:") + for code, index_role, file_role in sorted(role_mismatches): + print(f" - {code}:") + print(f" Index: {index_role or 'MISSING'}") + print(f" File : {file_role or 'MISSING'}") + else: + print("\nNo page role mismatches found. ✓") + + # Final status + if not (codes_in_index_not_in_files or codes_in_files_not_in_index or + description_mismatches or role_mismatches): + print("\n✅ All validations passed! Documentation is consistent.") + return True + else: + print("\n❌ Validation failed.") + return False + +def main(): + parser = argparse.ArgumentParser(description='Validate error code parity between index and individual files') + parser.add_argument('--index', help='Path to index.adoc file') + parser.add_argument('--dir', help='Path to directory containing error files') + parser.add_argument('--verbose', '-v', action='store_true', help='Show detailed differences for mismatches') + args = parser.parse_args() + + # Get the script's directory + script_dir = Path(__file__).parent.absolute() + + # Default paths if not specified + errors_dir = args.dir if args.dir else script_dir.parent / 'modules' / 'ROOT' / 'pages' / 'errors' / 'gql-errors' + index_file = args.index if args.index else errors_dir / 'index.adoc' + + # Validate that the paths exist + if not os.path.exists(errors_dir): + print(f"Error: Directory not found: {errors_dir}") + return 1 + + if not os.path.exists(index_file): + print(f"Error: Index file not found: {index_file}") + return 1 + + # Run validation + success = validate_error_parity(errors_dir, index_file, args.verbose) + + # Return return 0 if success + return 0 if success else 1 + +if __name__ == '__main__': + sys.exit(main()) \ No newline at end of file