doc: document fake ENOTFOUND as a system error

PR-URL: #26495
Fixes: #26484
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

doc/api/errors.md

@@ -573,6 +573,9 @@ program. For a comprehensive list, see the [`errno`(3) man page][].
 - `ENOTEMPTY` (Directory not empty): A directory with entries was the target
   of an operation that requires an empty directory — usually [`fs.unlink`][].
 
+- `ENOTFOUND` (DNS lookup failed): Indicates a DNS failure of either
+  `EAI_NODATA` or `EAI_NONAME`. This is not a standard POSIX error.
+
 - `EPERM` (Operation not permitted): An attempt was made to perform an
   operation that requires elevated privileges.
 

lib/internal/errors.js

@@ -432,8 +432,8 @@ function dnsException(code, syscall, hostname) {
   // If `code` is of type number, it is a libuv error number, else it is a
   // c-ares error code.
   if (typeof code === 'number') {
-    // FIXME(bnoordhuis) Remove this backwards compatibility nonsense and pass
-    // the true error to the user. ENOTFOUND is not even a proper POSIX error!
+    // ENOTFOUND is not a proper POSIX error, but this error has been in place
+    // long enough that it's not practical to remove it.
     if (code === lazyUv().UV_EAI_NODATA || code === lazyUv().UV_EAI_NONAME) {
       code = 'ENOTFOUND'; // Fabricated error name.
     } else {