dev-error-explainers

Purpose

dev-error-explainers is used to explain common developer errors offline and deterministically. The user pastes a piece of error text, the tool identifies the error type, gives the cause and fix suggestions, and cites official documentation sources where possible. It does not rely on an LLM, API, network, or telemetry, and the same input always returns the same result.

Main capabilities

The project contains seven small, pure JavaScript, zero-dependency modules, which respectively handle:

• CORS errors
• ESM/CommonJS module errors
• npm ERESOLVE dependency resolution errors
• ChunkLoadError
• Postgres/Supabase DATABASE_URL errors
• Postgres connection errors
• Next.js build errors

Each module recognizes the exact error text pasted by the developer (from the browser console, npm, next build, curl -I, Node.js stack traces, etc.), explains why it happened, and returns a specific fix, with links to primary sources where possible (MDN, Node.js docs, npm docs, PostgreSQL docs, Supabase docs, etc.).

The same engine can run as a library, CLI, GitHub Action, and MCP server. Six of the modules power free tools on iloveblogs.blog/tools, which can be tried in the browser.

Usage

As a library

Requires Node.js 20 or higher, and supports ES modules only. Everything can be imported from the package root, and each module can also be imported separately.

diagnose(text) Maps the results of all modules to a unified structure, with stable rule IDs, and redacts the input before analysis. Unknown input returns { matched: false, results: [] }, and does not give the closest guess.

redact(text) can also be exported from dev-error-explainers/redact .

As a CLI

You can pipe in the output of a failed command, or pass in a log file. Data is not sent anywhere.

Flags include:--only cors|esm|eresolve|build|database-url|database-connection|chunk-cache、--json、--node <version>、--client prisma|drizzle|pg|psql、--html-headers <file> --chunk-headers <file>、--help、--version。

npx dev-error-explainers mcp can start the MCP server.

Exit codes: 0 means an error was recognized, 2 means unrecognized (no guessing), 64 means usage error. Connection strings are always printed with the password masked.

Using in CI (GitHub Action)

When a step fails, the Action reads the saved log, writes the cause and fix to the job summary, and annotates the file and line when checking out files in the log. No network, no LLM, no token.

Using from an AI assistant (MCP)

Provides an MCP server containing one tool explain_error, letting the assistant check pasted errors against documented causes before guessing. Offline and deterministic; unrecognized input is reported truthfully. Supports Claude Code, Claude Desktop, Cursor, VS Code.

Using in Claude Code (plugin: skill + MCP)

This repository is also a Claude Code plugin marketplace. The plugin bundles the MCP server and a skill that tells Claude when to call it.

Suitable scenarios

• Developers encounter common errors locally or in CI and want a quick deterministic explanation and fix suggestions.
• Troubleshooting errors in environments without network access or where calling external APIs is not allowed.
• Automatically analyzing failed logs and generating summaries in GitHub Actions.
• Letting AI assistants query documented causes before answering error-related questions, reducing guessing.

Limitations

• Requires Node.js 20 or higher, and supports ES modules only.
• Unrecognized errors are reported as unrecognized, and no guessing is done.
• Redaction has limitations: the CLI, Action, and MCP server process input through redact() before analysis, but the DATABASE_URL doctor is an exception, as it reads the raw postgres:// lines (the exact characters of the password determine the diagnosis), but the password is never printed. When used directly as a library, six of the seven modules mask suspected secrets before echoing; the build error decoder does not, and it quotes the matching lines of the build output verbatim.
• The build error decoder has no primary source URL; its link points to an article on the author's website iloveblogs.blog.
• Not every rule cites a source.

Maintenance and Feedback

Maintained by Mahdi Ben Rhouma. CI runs the test suite on Node.js 20, 22, and 24. Unrecognized errors can be submitted via an issue with the exact text, the command that produced it, and the tool version; new rules require tests built from real errors. Incorrect diagnoses are also treated as bugs, with a separate template.