From 239b6d1d3fc86b04761f13cb5fa6b93acc8acfa7 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 Fixes: https://github.com/nodejs/node/issues/15038 Reviewed-By: James M Snell --- doc/api/errors.md | 154 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 137 insertions(+), 17 deletions(-) diff --git a/doc/api/errors.md b/doc/api/errors.md index 39053ab3d357dd..cdb6a65a4922df 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -588,6 +588,18 @@ Used as special type of error that can be triggered whenever Node.js detects an exceptional logic violation that should never occur. These are raised typically by the `assert` module. + +### 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_BUFFER_OUT_OF_BOUNDS @@ -614,6 +626,18 @@ Used when the native call from `process.cpuUsage` cannot be processed properly. Used when `c-ares` failed to set the DNS server. + +### 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 @@ -626,6 +650,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 @@ -652,20 +682,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 @@ -676,12 +718,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 @@ -837,6 +873,12 @@ to a Node.js API. Used when an Array is not of the expected length or in a valid range. + +### 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_BUFFER_SIZE @@ -913,6 +955,12 @@ passed in an options object. Used when an invalid or unknown file encoding is passed. + +### ERR_INVALID_PERFORMANCE_MARK + +Used by the Performance Timing API (`perf_hooks`) when a performance mark is +invalid. + ### ERR_INVALID_PROTOCOL @@ -1022,6 +1070,16 @@ Used when a callback is called more then once. can either be fulfilled or rejected but not both at the same time. The latter would be possible by calling a callback more then once. + +### 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_CRYPTO @@ -1041,9 +1099,17 @@ Used when a Node.js API is called in an unsupported manner. For example: `Buffer.write(string, encoding, offset[, length])` + +### ERR_OUTOFMEMORY + +Used generically to identify that an operation caused an out of memory +condition. + ### ERR_PARSE_HISTORY_DATA +Used by the `REPL` module when it cannot parse data from the REPL history file. + ### ERR_SOCKET_ALREADY_BOUND @@ -1066,6 +1132,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 @@ -1097,12 +1168,54 @@ const instance = new Socket(); instance.setEncoding('utf-8'); ``` - -### 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 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 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 in Transform streams when the stream finishes with data still in the write +buffer. ### ERR_UNESCAPED_CHARACTERS @@ -1147,6 +1260,12 @@ Used when a number value is out of range. Used when the V8 BreakIterator API is used but the full ICU data set is not installed. + +### ERR_VALID_PERFORMANCE_ENTRY_TYPE + +Used by the Performance Timing API (`perf_hooks`) when no valid performance +entry types were found. + ### ERR_VALUE_OUT_OF_RANGE @@ -1179,3 +1298,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