Open Source

dev-error-explainers

Paste a developer error, get the real cause and the fix. 7 pure JavaScript modules, 121 rules, no runtime dependencies. 6 of them are the same files that run in your browser on the tool pages below.

• Offline and deterministic: no LLM, no API, no network call. The same input gives the same answer.
• An error it does not recognise is reported as not recognised — never a closest guess.
• The CLI, the Action and the MCP server mask what looks like a secret before the analysis (except the DATABASE_URL doctor, which reads the raw URL and never prints its password); the limits of that masking are documented.
• A public corpus of 74 cases (real or labelled synthetic, each with its source) runs on every change.

Use it where the error happens

• TerminalREADME ↗

  Pipe a failing command into it. Nothing is sent anywhere.

  npm run build 2>&1 | npx dev-error-explainers

• CIFull workflow (pipefail, outcome) ↗

  A GitHub Action step that writes the cause and the fix of a failed build to the job summary, with annotations. Add it after a build step with id: build, continue-on-error: true and set -o pipefail.

  - name: Explain the failure
    if: steps.build.outcome == 'failure'
    uses: mahdibrr/dev-error-explainers@v0
    with:
      log-file: build.log

• AI assistantClaude Desktop, Cursor, VS Code ↗

  An MCP server with one tool, explain_error, so the assistant checks the documented cause before it guesses.

  claude mcp add dev-error-explainers -- npx -y -p dev-error-explainers dev-error-explainers-mcp

• Claude CodeREADME ↗

  A plugin that bundles the MCP server and a skill telling Claude when to call it.

  /plugin marketplace add mahdibrr/dev-error-explainers
  /plugin install dev-error-explainers@dev-error-explainers

In your own code: npm install dev-error-explainers (Node.js 20 or later).

Modules and the tool each one powers

• src/build-error-decoder.jsNext.js Build Error Decoder
• src/chunk-cache-explainer.jsChunkLoadError Cache Checker
• src/database-url-doctor.jsSupabase DATABASE_URL Doctor
• src/cors-error-explainer.jsCORS Error Explainer
• src/esm-cjs-explainer.jsNode.js ESM/CommonJS Error Explainer
• src/npm-eresolve-explainer.jsnpm ERESOLVE Explainer
• src/database-connection-explainer.jsDatabase connection errors — no browser version yet

Step-by-step fixes for the errors these modules explain

On this site, the tool pages run these modules in your browser. The separate “Paste your error” box on articles and search sends a cleaned error signature, never the pasted text (see the privacy policy). The library itself sends nothing.

Next.js + Supabase Production Incidents

A symptom-first index of what breaks after a Next.js + Supabase app is deployed — RLS that silently returns nothing, sessions lost in SSR, Stripe webhooks, cache invalidation — each tied to its evidence.

For teams running this stack in production: start from the symptom you see, not the feature you used. The repository also holds production checklists, debugging playbooks and three runnable examples (Next.js 15 caching and params, RLS tested with pgTAP, Stripe webhook idempotency).