A lightweight, rule-based command-line debugging assistant that explains why an error occurred and how to fix it — in plain English.
This tool is designed for developers who are tired of cryptic error messages and want quick, actionable explanations directly in the terminal.
Developers frequently encounter runtime errors, build failures, and Git issues that:
- Are hard to understand at first glance
- Require searching multiple sources
- Interrupt development flow
Most tools only show what failed. This CLI focuses on explaining why it failed and what to do next.
whyfail analyzes error messages or log files using a deterministic rule-based engine and provides:
- Error category (Node.js, Git, etc.)
- Human-friendly root cause explanation
- Clear fix suggestions
- Confidence score
The architecture is intentionally designed to be extensible, with AI-assisted reasoning planned as a future enhancement.
- User provides an error message or log file
- The input is normalized and scanned
- Known error patterns are matched against rule definitions
- Matches are ranked by strength to compute a confidence score
- The best match is returned with explanation and fix
- If no match is found, helpful next steps are suggested
- ✅ CLI-first, fast and lightweight
- ✅ Rule-based matching (reliable & deterministic)
- ✅ Dynamic confidence scoring based on match strength
- ✅ Category-based error classification (Node.js, Git, Network, Auth)
- ✅ Supports direct error text and log files
- ✅
--listcommand to display supported error patterns - 🔮 Planned: AI-assisted guessing for unknown patterns
npm install
npm linkwhyfail "EADDRINUSE: address already in use"whyfail --file error.logwhyfail --list✔ Issue identified
Category: Node.js
Cause: The port your app is trying to use is already occupied.
Fix: Stop the running process or change the port number.
Confidence: 90%
why-my-app-failed/
├── bin/ # CLI entry point
├── rules/ # Error pattern definitions
├── utils/ # Matcher engine
├── README.md
- Focuses on developer reasoning, not just tooling
- Uses a deterministic rule engine instead of blind AI calls
- Confidence scoring avoids misleading suggestions
- Transparent support via
--listcommand - Designed with clear future AI integration scope
- AI-assisted fallback for unknown or weakly-matched errors
- Ranking and displaying multiple possible causes
- Online pattern updates
- Community-contributed rule sets
- Stack trace summarization
Narendra Meshram Aspiring software engineer with a strong interest in building developer-focused tools.
MIT