diagnoseError(error, options) walks actual Error.cause chains with a default eight-layer bound (maxDepth 1–32). It detects cycles, exposes unknown causes honestly and returns structured chain entries with a translation for each layer. It never throws away the original error: result.original is the exact input reference and is deliberately non-enumerable so JSON output excludes it. The caller controls rethrowing, logging and exit behavior.
import { diagnoseError, renderDiagnosis } from "@deployanyway/error-translator";
try {
await loadConfig();
} catch (error) {
const diagnosis = diagnoseError(error, { mode: "rubber-duck" });
console.error(renderDiagnosis(diagnosis));
throw error; // preserve failure behavior and the original stack
}Options: mode plain/rubber-duck, maxDepth, includeStack (default false). Entries contain depth, name, message, optional code, translation and opt-in stack. stopped is complete/cycle/depth-limit; truncated reports incomplete traversal. Arbitrary primitive causes receive an explicit unknown translation. The caller's errors and causes are not mutated. AggregateError.errors is not flattened; this API follows the cause chain.
printf '%s' '{"message":"Config failed","cause":{"code":"ENOENT","message":"open config.json"}}' | error-translator --diagnose --json
node node_modules/@deployanyway/error-translator/examples/explain-failure.mjs ./missing-config.json--diagnose accepts a JSON error record from stdin or a quoted argument, with --max-depth and opt-in --include-stack. It rejects batch/catalog/list combinations. Translation/diagnosis exits 0; invalid input exits 2. The runnable filesystem example preserves application failure with exit 1. Messages and opt-in stacks can contain private data; this library does not redact them or run fixes.
Node 22.13+ or Node 24. MIT licensed. CLI flags, structured fields, ESM/CommonJS exports and declarations are covered by tests and installed-package checks. Existing 0.4 APIs remain available except the explicitly documented doggo-log redaction/text-context changes. Future incompatible public API changes require a major release; callers should consume structured fields rather than parse jokes. Exact humorous wording and seeded catalog choices are version-specific. No telemetry, external API keys or network service is needed for core use.
Run npm test, npm run lint, npm run format:check, npm run coverage, npm run test:types and npm run verify:package from a source checkout. Runnable examples are shipped under examples/. The root demo is https://deployanyway.github.io/.
46 built-in definitions cover filesystem, permissions, networking, module loading, streams, HTTP response lifecycle and JavaScript errors. Each has a specific explanation, likely causes and practical checks. Rubber-duck commentary has a distinct original line for every supported definition. No commands run automatically and unknown errors remain explicitly unrecognized.
npx @deployanyway/error-translator ERR_HTTP_HEADERS_SENT --mode rubber-duck
npx @deployanyway/error-translator --catalog --json
npx @deployanyway/error-translator --listimport { errorCatalog, translateError } from "@deployanyway/error-translator";
console.log(errorCatalog({ mode: "plain" }));
console.log(translateError({ code: "EACCES", message: "open config.json" }));errorCatalog(options?) returns independent structured translations for the complete catalog. --catalog prints all guidance, or JSON with --json. Explicit codes still take precedence over message matching. This is a focused Node/JavaScript debugging catalog, not diagnosis of every platform or framework error. Technical reference: https://nodejs.org/api/errors.html.
Version 0.4.0: install from npm with Node 22.13+ or Node 24. See MIGRATION.md for changes from 0.2.0.
Plain-English Node.js error explanations and debugging tips, because the stack trace has chosen violence.
Connection refused
What happened:
The application tried to connect to a service, but nothing accepted the connection.
Likely causes:
- The service is not running
- The host or port is incorrect
- A firewall actively rejected the connection
Try:
- Confirm that the service is running and listening on the configured host and port.
- Check connection settings and firewall rules.
Available on npm. Requires Node 22 or later. You can also run from source with Node 22 or 24:
git clone https://github.com/DeployAnyway/error-translator.git
cd error-translator
git checkout main
npm ci
node bin/cli.js ECONNREFUSEDInstall from npm:
npm install @deployanyway/error-translatorimport {
translateError,
renderTranslation,
} from "@deployanyway/error-translator";
const result = translateError("ECONNREFUSED");
console.log(result.suggestions);
console.log(renderTranslation(result));node bin/cli.js "TypeError: value is not a function" --jsonRun with npx: npx @deployanyway/error-translator ECONNREFUSED.
Accepts a nonempty string, an Error, or an object with string code, name,
or message fields. Returns a fresh structured object with code, title,
explanation, likelyCauses (string array), suggestions (string array), and mode.
An explicit code takes precedence, followed by a recognized name, then a
case-sensitive whole-word match in the message. Unknown errors return general
guidance with code UNKNOWN, or preserve an explicit unknown code.
Invalid input throws TypeError; unsupported modes throw RangeError.
Modes: plain (default) and rubber-duck, which preserves the guidance and adds commentary.
Returns readable text. Does not print, mutate the result, or exit the process. Invalid result shapes throw TypeError.
| Code/name | Guidance |
|---|---|
| EACCES | Permission denied |
| EPERM | Operation not permitted |
| EEXIST | Target already exists |
| ENOTDIR | Expected a directory |
| EISDIR | Expected a file |
| ENOTEMPTY | Directory is not empty |
| EMFILE | Too many open files |
| ENFILE | System file table exhausted |
| ENOSPC | No space left |
| EROFS | Read-only filesystem |
| EBUSY | Resource busy |
| EXDEV | Cross-device operation |
| EPIPE | Broken pipe |
| ECONNRESET | Connection reset |
| ETIMEDOUT | Operation timed out |
| ENOTFOUND | Name lookup failed |
| EAI_AGAIN | Temporary name lookup failure |
| EADDRNOTAVAIL | Local address unavailable |
| ECONNABORTED | Connection aborted |
| ENETUNREACH | Network unreachable |
| EHOSTUNREACH | Host unreachable |
| EINVAL | Invalid argument |
| ABORT_ERR | Operation aborted |
| ERR_INVALID_ARG_TYPE | Wrong argument type |
| ERR_INVALID_ARG_VALUE | Invalid argument value |
| ERR_OUT_OF_RANGE | Value outside allowed range |
| ERR_HTTP_HEADERS_SENT | Headers already sent |
| ERR_HTTP_INVALID_STATUS_CODE | Invalid HTTP status |
| ERR_INVALID_URL | Invalid URL |
| ERR_PACKAGE_PATH_NOT_EXPORTED | Package path not exported |
| ERR_PACKAGE_IMPORT_NOT_DEFINED | Package import not defined |
| ERR_INVALID_PACKAGE_CONFIG | Invalid package configuration |
| ERR_UNKNOWN_FILE_EXTENSION | Unknown module file extension |
| ERR_IMPORT_ATTRIBUTE_MISSING | Required import attribute missing |
| ERR_STREAM_WRITE_AFTER_END | Write after stream end |
| ERR_STREAM_DESTROYED | Stream destroyed |
| ERR_SOCKET_BAD_PORT | Invalid socket port |
| SyntaxError | Invalid JavaScript syntax |
| ReferenceError | Name is not available |
| RangeError | Value exceeds a permitted range |
| ECONNREFUSED | Connection refused |
| ENOENT | File or directory not found |
| EADDRINUSE | Address already in use |
| MODULE_NOT_FOUND | Module not found |
| ERR_MODULE_NOT_FOUND | ES module not found |
| TypeError | Unexpected value type |
Translations describe likely causes, not a diagnosis. Keep the original error and stack trace for context. No AI API or remote service is used.
error-translator <code or message> [options]
| Option | Behavior |
|---|---|
--help, -h |
Show usage |
--version, -v |
Show package version |
--json |
Print structured JSON |
--mode plain |
Select plain or rubber-duck mode |
Quote messages containing spaces or shell punctuation. Use -- before a message
beginning with a dash. No stdin support is included in the MVP.
Exit code 0 means translation/help/version succeeded, including unknown errors.
Exit code 2 means invalid arguments. The library never exits.
npm ci
node examples/basic.js
npm test
npm run lint
npm run format:check
npm pack --dry-runES modules, Node's test runner, zero production dependencies. CI checks Node 22
and 24. Error definitions live in src/definitions.js; API and renderer in
src/index.js; CLI in bin/cli.js. Only runtime files, README, MIT license,
changelog, and package metadata are packaged.
See CONTRIBUTING.md. Accurate, actionable guidance and tests are welcome.
MIT.
Tools for developers who probably know better.
Keep the debugging guidance, add workplace-safe rubber-duck commentary. Plain output remains the default.
npx @deployanyway/error-translator ECONNREFUSED --mode rubber-duckAPI (import the named functions from this package):
translateError("ENOENT", { mode: "rubber-duck" });import { translateErrors, listErrors } from "@deployanyway/error-translator";
const results = translateErrors(["ENOENT", { code: "ECONNREFUSED" }], {
mode: "rubber-duck",
});
console.log(results[0].suggestions);
console.log(listErrors());Batches accept 1–100 errors in order, fail on malformed entries and return independent arrays. This is deterministic guidance, not diagnosis. Unknown errors remain unknown: keep the original stack.
echo "ECONNREFUSED" | node bin/cli.js --mode rubber-duck
node bin/cli.js --batch --json < errors.json
node bin/cli.js --list --jsonWithout arguments, read UTF-8 stdin (maximum 256 KiB). Arguments take precedence. --batch expects a JSON array; --json emits an array of results. --list catalogs supported codes. Status 0 means translated, including unknown errors; status 2 means invalid input.
git clone --branch main https://github.com/DeployAnyway/error-translator.git
cd error-translator
npm ci
npm run build
node bin/cli.js --helpVersion 0.3 provides useful declaration types, ESM/CommonJS exports, installed-archive checks, and coverage gates (90% statements/lines/functions, 85% branches). CI covers Linux Node 22/24 and Windows/macOS Node 24. Node 22.13+ is required. No runtime dependencies, telemetry or network requests.
From a source checkout: npm ci, npm run build, npm run coverage, npm run test:types, npm run verify:package. Pack verification installs a temporary local archive and checks module entries, types, executable and offline npm exec.
Contribution guide · Conduct · Security · Roadmap · Migration.
Tools for developers who probably know better. Software nobody requested, built with questionable priorities, and shipped with absolute confidence!