mahdibrr/dev-error-explainers

**Paste an error. Get a deterministic explanation.**
No LLM · no API · no network · no telemetry
Output:
Seven small, **pure** JavaScript modules with zero dependencies. Each one recognises the
exact 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: the CLI, the Action and the MCP server pass the input through redact()
before it is analysed, with one exception: the DATABASE_URL doctor reads the raw
postgres:// line (a password's exact characters decide the diagnosis), and never
prints that password. Used directly as a library, six of the seven
modules mask what looks like a secret before echoing it back; **the build-error decoder
does not** — it quotes the matching lines of your build output as they are. Redaction
has limits: see what it does not catch.
Six of them power the free tools on **iloveblogs.blog/tools**,
where you can try each one in the browser.
| Module | Main export (dev-error-explainers) | What it explains | Try it live |
|---|---|---|---|
| cors-error-explainer | diagnoseCors | Chrome / Firefox / Safari "blocked by CORS policy" errors: missing or wrong Access-Control-Allow-* headers, preflight failures, credentials, mixed content — with a fix for your stack | CORS Error Explainer |
| esm-cjs-explainer | explainEsmCjs | ERR_REQUIRE_ESM, "Cannot use import statement outside a module", "exports is not defined in ES module scope", ERR_UNKNOWN_FILE_EXTENSION ".ts", ERR_MODULE_NOT_FOUND, ERR_PACKAGE_PATH_NOT_EXPORTED — aware of your Node.js version | ESM/CJS Error Explainer |
| npm-eresolve-explainer | analyseEresolveLog | npm ERR! ERESOLVE peer-dependency conflicts: who asks for which range, what is installed, and why they do not intersect | npm ERESOLVE Explainer |
| chunk-cache-explainer | diagnoseChunkCache | ChunkLoadError / "Loading chunk failed" after a deploy: reads your response headers and finds the stale HTML, the CDN cache hit or the SPA fallback | ChunkLoadError Cache Checker |
| database-url-doctor | diagnoseDatabaseUrl | Postgres / Supabase connection strings: pooler vs direct, port 5432 vs 6543, pgbouncer, SSL, unencoded password characters — with a corrected URL for Prisma, Drizzle, pg or psql | DATABASE_URL Doctor |
| build-error-decoder | decodeBuildError | Failing next build / next dev output: Suspense bailouts, dynamic server usage, window is not defined, hydration mismatches, module resolution, heap out of memory, EADDRINUSE… | Next.js Build Error Decoder |
| database-connection-explainer | explainDatabaseConnection | "Can't connect to the database" from Node.js apps on PostgreSQL: ECONNREFUSED (including ::1 localhost), ETIMEDOUT, ENOTFOUND, Prisma P1000 / P1001 / P1017, password authentication failed, no pg_hba.conf entry, too many clients, self-signed certificates. Generic network codes are only diagnosed next to a Postgres signal | No browser tool yet — rules and sources |