error-explainer

Transform cryptic JavaScript & TypeScript error messages into human-readable explanations with actionable fix suggestions.

Why?

Error messages like Cannot read properties of undefined (reading 'name') are confusing — especially for beginners and junior developers. error-explainer translates them into plain English with a clear reason and a concrete fix suggestion.

Perfect for:

• 🧑‍💻 Beginner-friendly developer tools
• 🤖 AI-powered IDEs and coding assistants
• 🛠️ Custom error dashboards and loggers
• 📚 Learning platforms and code editors

Install

npm install error-explainer

Quick Start

import { explain } from 'error-explainer';

const result = explain("Cannot read properties of undefined (reading 'name')");

console.log(result);
// {
//   original:   "Cannot read properties of undefined (reading 'name')",
//   reason:     "You are trying to access the property `name` on a value that is `undefined`.",
//   suggestion: "Add a null-check before accessing the property: `if (value) { value.name }` or use optional chaining: `value?.name`.",
//   category:   "TypeError",
//   severity:   "high"
// }

API

explain(error, options?)

Explains a single error. Accepts a string, an Error object, or any unknown thrown value.

import { explain } from 'error-explainer';

// From a string
explain("user is not defined");

// From a caught Error object
try {
  doSomething();
} catch (err) {
  const info = explain(err);
  console.log(info.reason);
  console.log(info.suggestion);
}

Options

| Option | Type | Default | Description | |------------------|---------|---------|------------------------------------------| | includeCauses | boolean | false | Include a commonCauses string array | | includeDocs | boolean | false | Include an MDN/docs URL when available |

explain("Cannot find module 'react'", {
  includeCauses: true,
  includeDocs: true,
});
// {
//   ...
//   commonCauses: ["Package not installed (`npm install` not run)", ...],
//   docs: "https://nodejs.org/api/modules.html"
// }

quickExplain(error)

Returns only reason and suggestion — ideal for tooltips and compact logging.

import { quickExplain } from 'error-explainer';

quickExplain("Maximum call stack size exceeded");
// {
//   reason:     "A function is calling itself without a proper base case ...",
//   suggestion: "Add a base/termination condition to your recursive function ..."
// }

explainAll(errors, options?)

Explain multiple errors at once.

import { explainAll } from 'error-explainer';

const results = explainAll([
  "Failed to fetch",
  "Assignment to constant variable",
  new TypeError("foo is not a function"),
]);

Return Type: ExplainedError

interface ExplainedError {
  original:      string;          // The raw input error message
  reason:        string;          // Human-readable explanation
  suggestion:    string;          // Actionable fix
  category:      ErrorCategory;  // "TypeError" | "ReferenceError" | ...
  severity:      "low" | "medium" | "high";
  commonCauses?: string[];        // With includeCauses: true
  docs?:         string;          // With includeDocs: true
}

Supported Error Types

| Category | Example Message | |------------------|--------------------------------------------------------------| | TypeError | Cannot read properties of undefined (reading 'x') | | TypeError | Cannot read properties of null | | TypeError | foo is not a function | | TypeError | Assignment to constant variable | | TypeError | undefined is not iterable | | ReferenceError | user is not defined | | SyntaxError | Unexpected token '}' | | SyntaxError | Unexpected end of input | | RangeError | Maximum call stack size exceeded | | PromiseError | Unhandled promise rejection | | NetworkError | Failed to fetch / net::ERR_* | | ModuleError | Cannot find module 'react' |

Integration Example — Express Error Handler

import { explain } from 'error-explainer';

app.use((err, req, res, next) => {
  const info = explain(err, { includeCauses: true });
  res.status(500).json({
    error:      info.original,
    reason:     info.reason,
    suggestion: info.suggestion,
    severity:   info.severity,
  });
});

Integration Example — React Error Boundary

import { explain } from 'error-explainer';

class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error) {
    const info = explain(error);
    console.warn(`[${info.severity.toUpperCase()}] ${info.reason}`);
    console.info(`Fix: ${info.suggestion}`);
  }
}

License

MIT © error-explainer contributors