smart-error-explainer

Turn raw Node.js errors into human-friendly explanations and suggested fixes. Works as a small library and a CLI.

• Library API: explain(error) returns a structured explanation object
• CLI: smart-error reads from stdin, a file, or --error "..."

Install

npm i smart-error-explainer
# or
pnpm add smart-error-explainer
# or
yarn add smart-error-explainer

For the CLI:

npx smart-error-explainer # via npx (once published)
# or if installed globally
npm i -g smart-error-explainer
smart-error --help

Usage (Library)

const { explain } = require('smart-error-explainer');

try {
  require('expressx');
} catch (err) {
  const info = explain(err);
  console.log(info.title);
  console.log(info.explanation);
  console.log(info.fixes);
}

Usage (CLI)

• Pipe an error:

some-command 2>&1 | smart-error

• From a file:

smart-error --file error.log

• From a string:

smart-error --error "Cannot find module 'express'"

• JSON output:

smart-error --error "ReferenceError: foo is not defined" --json

Output shape

interface Explanation {
  title: string;
  explanation: string;
  probableCauses: string[];
  fixes: string[];
  references: { label: string; url: string }[];
  confidence: number; // 0..1
  matchedRule: string | null; // e.g. "node.module_not_found"
  raw: string; // normalized input
}

Supported patterns (initial)

• MODULE_NOT_FOUND / "Cannot find module 'x'"
• EADDRINUSE (port in use)
• EACCES (permission denied)
• ENOENT (file not found)
• SyntaxError (common)
• ReferenceError (not defined)
• TypeError (x is not a function)
• Network: ECONNREFUSED, ETIMEDOUT

Contributions for more rules are welcome. See src/index.js RULES for examples.

Roadmap

• More granular rules (Next.js, Express, TypeScript, Prisma, Playwright, etc.)
• Confidence scoring improvements
• Links to official docs and curated blog posts for each rule
• Optional telemetry-free heuristics (e.g., check for package.json deps)

Local development

# run CLI help
npm start

# quick demo
node -e "require('./src/index').demo()"

# try CLI with a sample error
node -e "console.error('Error: Cannot find module \'express\'')" | node bin/smart-error.js

Publishing to npm

1. Update package.json version
2. Ensure files are correct: files field includes src/, bin/, index.d.ts, LICENSE, README.md
3. Login and publish:

npm login
npm publish --access public

Package name: smart-error-explainer.

License

MIT © Harsh Patel