Dev error explainers

dev-error-explainers

Paste an error. Get a deterministic explanation.

Version 0.4.0 adds an explicit environment audit and native assistant setup. Public database helpers now return masked metadata and URL templates; see the migration notes before upgrading from 0.2.x. The 1.0 verification record remains incomplete.

No LLM · no API · no network · no telemetry

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

npm install dev-error-explainers

import { detect, explainEsmCjs } from 'dev-error-explainers';

const error = 'Error [ERR_REQUIRE_ESM]: require() of ES Module /app/node_modules/node-fetch/src/index.js from /app/index.js not supported.'; console.log(detect(error)); const { findings } = explainEsmCjs({ error, nodeVersion: '20.10.0' }); console.log(findings[0].title, findings[0].fixes.map((f) => f.title));

Output:

[ 'esm-cjs-explainer' ]

ERR_REQUIRE_ESM — require() of an ES module [ 'Upgrade Node.js (you are on 20.10.0)', 'Use dynamic import() from CommonJS', 'Convert the calling file to ESM' ]

Eight small, pure JavaScript modules with zero runtime dependencies: seven error explainers and one explicit environment-file audit. The seven explainers recognise error text a developer pastes (from the browser console, npm, next build, curl -I, a Node.js stack trace…), explains *why* it happens, and returns concrete fixes with a link to the primary source where one exists (MDN, the Node.js docs, the npm docs, the PostgreSQL docs, the Supabase docs…). The same engine runs as a library, a CLI, a GitHub Action and an MCP server.

Secrets: error diagnosis in the CLI, Action and MCP server passes the input through redact() before it is analysed, with one exception in error diagnosis: the DATABASE_URL doctor reads the raw postgres:// line (a password's exact characters decide the diagnosis), and never prints that password. Library diagnostics also mask recognised credentials in build evidence and database query components. The separate auditEnv / audit_env audit inspects raw values locally to classify keys, but returns no input keys or values. Public database parsing helpers now return masked metadata; correctedWithPassword is a deprecated alias returning masked corrections. See the 0.3 migration and confidentiality limits and what redaction does not catch.

Six of them power the free tools on [iloveblogs.blog/tools](https://www.iloveblogs.blog/tools), where you can try each one in the browser.

Evidence: most findings cite the primary source they were checked against. The build-error decoder has no primary-source URL; its links point to articles on the author's site, iloveblogs.blog.

Node.js 20 or later. ES modules only.

See input/resource limits, the prospective evaluation report, and the execution record for the measured scope and gaps. npm run check:drift, npm run typecheck and npm test are release gates. The development fixture score is not independent accuracy.

Usage

Everything is available from the package root, and each module can also be imported on its own:

import { diagnose } from 'dev-error-explainers/cors-error-explainer';

const r = diagnose({ error: "Access to fetch at 'https://api.example.com/data' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.", }); r.isCorsProblem; // true r.findings; // what is wrong, why, and the source r.fix; // a fix for the detected (or guessed) stack

import {

analyseEresolveLog, diagnoseDatabaseUrl, diagnoseChunkCache, decodeBuildError, explainDatabaseConnection, } from 'dev-error-explainers';

analyseEresolveLog(npmOutput); // { detected, code, conflicts: [...] } diagnoseDatabaseUrl(process.env.DATABASE_URL, { client: 'prisma' }); // { ok, kind, findings, corrected } diagnoseChunkCache({ htmlHeaders, chunkHeaders }); // headers from curl -I decodeBuildError(nextBuildOutput); // matched rules, most severe first explainDatabaseConnection({ error: stackTrace }); // { recognised, findings, related }

detect(text)

Returns the names of the modules that recognise text, in a fixed order, or []. Each module is asked through its own recogniser — detect adds no heuristics of its own. Note that chunk-cache-explainer reads HTTP response headers (the output of curl -I), not the ChunkLoadError message itself; the message alone is recognised by build-error-decoder.

Audit an environment file

import { auditEnv } from 'dev-error-explainers';

const audit = auditEnv(envText, { environment: 'production' }); // { version: '0.1', status, assignments, matched, redactions, results }

npx dev-error-explainers --only env --environment production --json .env.local

This mode never prints file contents or assignment values. The MCP equivalent is audit_env({ env: envText, environment: "production" }). Error auto-diagnosis and the GitHub Action do not automatically treat logs as environment files. An audit with no findings does not certify that the configuration is safe. See the parsing scope, rules and limits.

JSON contract

Every module has its own result shape. diagnose(text) maps all of them onto one shape with stable rule ids, after redacting the input — the shape the CLI prints with --json, the GitHub Action renders and the MCP server returns:

import { diagnose } from 'dev-error-explainers'; // or 'dev-error-explainers/contract'

diagnose('FATAL: password authentication failed for user "andym"'); // { version: '0.1', matched: true, redactions: 0, // results: [{ rule: 'database-connection.password-auth-failed', family: 'database-connection', // severity: 'critical', confidence: 'high', title, cause, fixes, evidence, module }] }

Unknown input gives { matched: false, results: [] } — never a closest guess. The shape, the full rule table, the confidence semantics and the redaction limits are in docs/CONTRACT.md. A public corpus of real pasted errors with their expected results lives in fixtures/, each case with its source. redact(text) is exported too (dev-error-explainers/redact).

CLI

Pipe a failing command into it, or pass a log file. Nothing is sent anywhere.

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

npx dev-error-explainers < error.log npx dev-error-explainers --text "Error [ERR_REQUIRE_ESM]: require() of ES Module …" --node 18.17.0 npx dev-error-explainers --json < error.log # the contract result (docs/CONTRACT.md)

Flags: --only cors|esm|eresolve|build|database-url|database-connection|chunk-cache|env, --json, --node , --client prisma|drizzle|pg|psql, --html-headers --chunk-headers , --help, --version. npx dev-error-explainers mcp starts the MCP server.

Exit codes: 0 an error was recognised, 2 nothing recognised (nothing is guessed), 64 usage error. A connection string is always printed with its password masked.

Use it in CI (GitHub Action)

When a step fails, the Action reads the log you saved from it and writes the cause and the fix to the job summary, with annotations on the file and line when the log names a file in your checkout. No network, no LLM, no token.

      - name: Build

id: build continue-on-error: true # let the explain step run… shell: bash run: | set -o pipefail npm run build 2>&1 | tee build.log

• name: Explain the