DOC-12321: Add docs for finderr tool and builtin function

modules/ROOT/nav.adoc

@@ -313,6 +313,7 @@ include::cli:partial$cbcli/nav.adoc[]
  ** xref:cli:cbtools/cbtransfer.adoc[cbtransfer]
  ** xref:cli:cbtools/cbworkloadgen.adoc[cbworkloadgen]
  ** xref:cli:couchbase-server.adoc[couchbase-server]
+ ** xref:cli:finderr.adoc[finderr]
  ** xref:cli:mctimings.adoc[mctimings]
  ** xref:cli:mcstat.adoc[mcstat]
 * xref:rest-api:rest-intro.adoc[REST API Reference]

modules/cli/pages/finderr.adoc

@@ -0,0 +1,221 @@
+= finderr
+:description: pass:q[The [.cmd]`finderr` tool returns the full details of any Query service or cbq shell error.]
+:page-status: Couchbase Server 7.6.4
+:page-topic-type: reference
+
+[abstract]
+{description}
+
+== Syntax
+
+The basic syntax is:
+
+----
+finderr <number|string|regex>
+----
+
+== Description
+
+ifeval::['{page-component-version}' == '7.6'] 
+This tool is only available in Couchbase Server 7.6.4 and later.
+endif::[]
+
+Depending upon your platform, this tool is at the following locations:
+
+[cols="1,3"]
+|===
+| Operating system | Location
+
+| Linux
+| [.path]`/opt/couchbase/bin/`
+
+| Windows
+| [.path]`C:\Program Files\Couchbase\Server\bin\`
+
+| Mac OS X
+| [.path]`/Applications/CouchbaseServer.app/Contents/Resources/couchbase-core/bin/`
+|===
+
+== Options
+
+The tool takes a single argument, which must be one of the following:
+
+number::
+A number representing an error code.
+In this case, the tool returns the full details of the error matching the error code.
+
+string::
+A string.
+In this case, the tool searches for the target string in all of the error message fields except for `USER ERROR`, and returns the full details of any errors that match the string.
+
+regex::
+A regular expression.
+In this case, the tool searches for the regular expression in all of the error message fields except for `USER ERROR`, and returns the full details of any errors that match the pattern.
+
+== Output
+
+If the tool finds a single error that matches the find argument, it outputs the full details of the error.
+
+If the tool finds multiple errors that match the find argument, it outputs a list showing the code and description of each matching error.
+You can use the tool again, passing the code or description as an argument, to get the full details of any of these errors.
+
+Full error details include some or all of the following fields.
+
+[options="header", cols="50a,147a"]
+|===
+|Name|Description
+
+|**APPLIES TO**
+|One of the following:
+
+* `cbq-shell`: The error applies to the cbq shell.
+* `Server`: The error applies to the server.
+
+|**CODE**
+|A number representing the error.
+
+|**DESCRIPTION**
+|Message describing why the error occurred.
+
+|**REASON**
+|List of possible causes of the error.
+
+|**USER ACTION**
+|List of possible steps a user can take to mitigate the error.
+
+|**USER ERROR**
+|One of the following:
+
+* `Yes`: The error was caused by the user.
+* `No`: The error was caused by other services, or was internal to the server.
+* `Maybe`: A combination of both.
+|===
+
+NOTE: The error details also include a `SYMBOL` field, which contains a representation string for the error.
+This field is for internal use only, and is not shown in the output.
+However, the tool does search this field when the find argument is a string or a regular expression.
+
+== Examples
+
+[[finderr-ex1]]
+.Find error details by code number
+====
+.Command
+[source,sh]
+----
+./finderr 5011
+----
+
+.Output
+----
+CODE
+  5011 (error)
+
+
+DESCRIPTION
+  Abort: «reason»
+
+
+REASON
+  The SQL++ abort() function was called in the statement.
+  e.g. SELECT abort('An example cause')
+
+
+USER ERROR
+  Yes
+
+
+APPLIES TO
+  Server
+----
+====
+
+[[finderr-ex2]]
+.Find error details by matching a string
+====
+.Command
+[source,sh]
+----
+./finderr "A semantic error is present in the statement."
+----
+
+.Output
+----
+CODE
+  3100 (error)
+
+
+DESCRIPTION
+  A semantic error is present in the statement.
+
+
+REASON
+  The statement includes portions that violate semantic constraints.
+
+
+USER ACTION
+  The cause will contain more detail on the violation; revise the statement and re-submit.
+
+
+USER ERROR
+  Yes
+
+
+APPLIES TO
+  Server
+----
+====
+
+[[finderr-ex3]]
+.Find multiple errors by matching a string
+====
+.Command
+[source,sh]
+----
+./finderr "semantic"
+----
+
+.Output
+----
+Matching errors
+  3100 A semantic error is present in the statement.
+  3220 «name» window function «clause» «reason»
+  3300 recursive_with semantics: «cause»
+----
+====
+
+[[finderr-ex4]]
+.Find multiple errors by matching a regular expression
+====
+.Command
+[source,sh]
+----
+./finderr "[UI][NP]SERT"
+----
+
+.Output
+----
+Matching errors
+  3150 MERGE with ON KEY clause cannot have document key specification in INSERT action.
+  3160 MERGE with ON clause must have document key specification in INSERT action
+  3180 MERGE with ON KEY clause cannot have USE INDEX hint specified on target.
+  5006 Out of key validation space.
+  5050 No INSERT key for «document»
+  5060 No INSERT value for «document»
+  5070 Cannot INSERT non-string key «key» of type «type»
+  5071 Cannot INSERT non-OBJECT options «options» of type «type»
+  5072 No UPSERT key for «value»
+  5073 Cannot act on the same key multiple times in an UPSERT statement
+  5075 No UPSERT value for «value»
+  5078 Cannot UPSERT non-string key «key» of type «type».
+  5079 Cannot UPSERT non-OBJECT options «value» of type «type».
+  5330 Multiple INSERT of the same document (document key «key») in a MERGE statement
+ 12036 Error in INSERT of key: «key»
+ 15005 No keys to insert «details»
+----
+====
+
+== See Also
+
+* The {sqlpp} xref:n1ql:n1ql-language-reference/metafun.adoc#finderr[FINDERR()] function
+* xref:n1ql:n1ql-language-reference/n1ql-error-codes.adoc[]