From d6619b9ad404113cfb7734ec0badbfea8af695e9 Mon Sep 17 00:00:00 2001 From: George Bezerra Date: Sun, 3 Sep 2017 05:27:44 -0300 Subject: [PATCH] doc: document missing error codes There are discrepancies between the errors defined in `lib/internal/errors.js` and those documented in `doc/api/errors.md`. Some of the errors recently defined are not documented, while others were removed, but still have entries in the docs. This commit fills in those gaps in the documentation. PR-URL: https://github.com/nodejs/node/pull/15160 Backport-PR-URL: https://github.com/nodejs/node/pull/16556 Fixes: https://github.com/nodejs/node/issues/15038 Reviewed-By: James M Snell --- doc/api/errors.md | 146 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 129 insertions(+), 17 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index eac21bae562413..6a9568952a846c 100755 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -586,6 +586,30 @@ found [here][online]. Used generically to identify that an iterable argument (i.e. a value that works with `for...of` loops) is required, but not provided to a Node.js API. + +### ERR_ASYNC_CALLBACK + +Used with `AsyncHooks` to indicate an attempt of registering something that is +not a function as a callback. + + +### ERR_ASYNC_TYPE + +Used when the type of an asynchronous resource is invalid. Note that users are +also able to define their own types when using the public embedder API. + + +### ERR_ENCODING_INVALID_ENCODED_DATA + +Used by the `util.TextDecoder()` API when the data provided is invalid +according to the encoding provided. + + +### ERR_ENCODING_NOT_SUPPORTED + +Used by the `util.TextDecoder()` API when the encoding provided is not one of +the [WHATWG Supported Encodings][]. + ### ERR_FALSY_VALUE_REJECTION @@ -598,6 +622,12 @@ with a falsy value (e.g. `null`). Used when headers have already been sent and another attempt is made to add more headers. + +### ERR_HTTP_INVALID_CHAR + +Used when an invalid character is found in an HTTP response status message +(reason phrase). + ### ERR_HTTP_INVALID_STATUS_CODE @@ -624,20 +654,32 @@ forbidden. ### ERR_HTTP2_CONNECT_SCHEME -The HTTP/2 requests using the `CONNECT` method, the `:scheme` pseudo-header is +For HTTP/2 requests using the `CONNECT` method, the `:scheme` pseudo-header is forbidden. - -### ERR_HTTP2_ERROR - -A non-specific HTTP/2 error has occurred. - ### ERR_HTTP2_FRAME_ERROR Used when a failure occurs sending an individual frame on the HTTP/2 session. + +### ERR_HTTP2_HEADER_REQUIRED + +Used when a required header is missing in an HTTP/2 message. + + +### ERR_HTTP2_HEADER_SINGLE_VALUE + +Used when multiple values have been provided for an HTTP header field that +required to have only a single value. + + +### ERR_HTTP2_HEADERS_AFTER_RESPOND + +Used when trying to specify additional headers after an HTTP/2 response +initiated. + ### ERR_HTTP2_HEADERS_OBJECT @@ -648,12 +690,6 @@ Used when an HTTP/2 Headers Object is expected. Used when an attempt is made to send multiple response headers. - -### ERR_HTTP2_HEADER_SINGLE_VALUE - -Used when multiple values have been provided for an HTTP header field that -required to have only a single value. - ### ERR_HTTP2_INFO_HEADERS_AFTER_RESPOND @@ -811,6 +847,12 @@ Used when a given index is out of the accepted range (e.g. negative offsets). Used generically to identify that an argument of the wrong type has been passed to a Node.js API. + +### ERR_INVALID_ASYNC_ID + +Used with `AsyncHooks` when an invalid `asyncId` or `triggerAsyncId` is passed. +An id less than -1 should never happen. + ### ERR_INVALID_CALLBACK @@ -846,6 +888,12 @@ communication channel to a child process. See [`subprocess.send()`] and Used generically to identify when an invalid or unexpected value has been passed in an options object. + +### ERR_INVALID_PERFORMANCE_MARK + +Used by the Performance Timing API (`perf_hooks`) when a performance mark is +invalid. + ### ERR_INVALID_PROTOCOL @@ -935,12 +983,28 @@ only used in the [WHATWG URL API][] for strict compliance with the specification native Node.js APIs, `func(undefined)` and `func()` are treated identically, and the [`ERR_INVALID_ARG_TYPE`][] error code may be used instead. + +### ERR_NAPI_CONS_FUNCTION + +Used by the `N-API` when a constructor passed is not a function. + + +### ERR_NAPI_CONS_PROTOTYPE_OBJECT + +Used by the `N-API` when `Constructor.prototype` is not an object. + ### ERR_NO_ICU Used when an attempt is made to use features that require [ICU][], while Node.js is not compiled with ICU support. + +### ERR_OUTOFMEMORY + +Used generically to identify that an operation caused an out of memory +condition. + ### ERR_SOCKET_ALREADY_BOUND Used when an attempt is made to bind a socket that has already been bound. @@ -962,6 +1026,11 @@ invalid value. Used when data cannot be sent on a socket. + +### ERR_SOCKET_CLOSED + +Used when an attempt is made to operate on an already closed socket. + ### ERR_SOCKET_DGRAM_NOT_RUNNING @@ -979,12 +1048,54 @@ Node.js does not allow `stdout` or `stderr` Streams to be closed by user code. Used when an attempt is made to close the `process.stdout` stream. By design, Node.js does not allow `stdout` or `stderr` Streams to be closed by user code. - -### ERR_UNKNOWN_BUILTIN_MODULE + +### ERR_TLS_CERT_ALTNAME_INVALID + +Used with TLS, when the hostname/IP of the peer does not match any of the +subjectAltNames in its certificate. + + +### ERR_TLS_DH_PARAM_SIZE + +Used with TLS when the parameter offered for the Diffie-Hellman (`DH`) +key-agreement protocol is too small. By default, the key length must be greater +than or equal to 1024 bits to avoid vulnerabilities, even though it is strongly +recommended to use 2048 bits or larger for stronger security. + + +### ERR_TLS_HANDSHAKE_TIMEOUT + +A TLS error emitted by the server whenever a TLS/SSL handshake times out. In +this case, the server must also abort the connection. + + +### ERR_TLS_RENEGOTIATION_FAILED + +Used when a TLS renegotiation request has failed in a non-specific way. + + +### ERR_TLS_REQUIRED_SERVER_NAME + +Used with TLS, when calling the `server.addContext()` method without providing +a hostname in the first parameter. + + +### ERR_TLS_SESSION_ATTACK + +Used when an excessive amount of TLS renegotiations is detected, which is a +potential vector for denial-of-service attacks. + + +### ERR_TRANSFORM_ALREADY_TRANSFORMING + +Used in Transform streams when the stream finishes while it is still +transforming. + + +### ERR_TRANSFORM_WITH_LENGTH_0 -Used to identify a specific kind of internal Node.js error that should not -typically be triggered by user code. Instances of this error point to an -internal bug within the Node.js binary itself. +Used in Transform streams when the stream finishes with data still in the write +buffer. ### ERR_UNKNOWN_SIGNAL @@ -1052,3 +1163,4 @@ Used when a given value is out of the accepted range. [syscall]: http://man7.org/linux/man-pages/man2/syscall.2.html [try-catch]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch [vm]: vm.html +[WHATWG Supported Encodings]: util.md#whatwg-supported-encodings