errorplain

Turn ugly JavaScript errors into useful explanations.

One small problem. One obvious API. Very little setup. Immediate value.

TypeError: Cannot read properties of undefined (reading 'avatar')

technically correct — and still useless. Which object was undefined? Which property chain failed? Where do you fix it?

Install

npm i errorplain

Usage

import { explain, printError } from "errorplain";

try {
  renderUser();
} catch (error) {
  console.log(explain(error));           // full explanation as text
  // or
  printError(error);                     // prints via console.error
}

What you get

Tried to read "avatar" from undefined

The code accessed property "avatar" on a value that is undefined.
Common causes:
  · async data not loaded yet (the object came back undefined)
  · optional field actually missing on this sample
  · wrong variable name
Fix: optional chaining, ensure data arrived before render, or guard early.

Location: src/components/Profile.tsx:41:28

Structured result

const { kind, headline, details, location } = explain(error);
// kinds: TypeError | SyntaxError | ModuleNotFound | FileNotFound
//        | ConnectionRefused | Network | RangeError | Unknown

Covered MVP patterns

| original | explanation | |---|---| | Cannot read properties of undefined (reading 'x') | missing object + property named, causes list | | Unexpected token } in JSON at position 82 | Invalid JSON + position + causes | | Expected double-quoted property name in JSON at position 16 (Node 25 style) | same, adapted | | Cannot find module '@/services/user' | relative/absolute hint + closest files on disk | | ENOENT: no such file or directory, open 'x' | file not found + cwd note | | connect ECONNREFUSED 127.0.0.1:5432 | nothing listening at host:port | | fetch failed (+ cause) | network failure with the low-level cause |

Unmatched errors fall back to the raw message — never worse than before.

API

explain(error)      // structured explanation with .toString()
formatError(error)  // plain string
printError(error)   // console.error the explanation

Zero dependencies. ESM + CJS + .d.ts. Node >= 18.

License

MIT