dev-error-explainers

dev-error-explainers

Pega un error. Obtén una explicación determinista.

Sin LLM · sin API · sin red · sin telemetría

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));

Salida:

[ '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'
]

Siete módulos pequeños y puros de JavaScript con cero dependencias. Cada uno reconoce el texto exacto del error que un desarrollador pega (desde la consola del navegador, npm, next build, curl -I, un stack trace de Node.js…), explica por qué ocurre y devuelve soluciones concretas con un enlace a la fuente principal cuando existe (MDN, la documentación de Node.js, la documentación de npm, la documentación de PostgreSQL, la documentación de Supabase…). El mismo motor funciona como librería, CLI, GitHub Action y servidor MCP.

Secretos: la CLI, la Action y el servidor MCP pasan la entrada por redact() antes de analizarla, con una excepción: el doctor de DATABASE_URL lee la línea cruda de postgres:// (los caracteres exactos de una contraseña deciden el diagnóstico) y nunca imprime esa contraseña. Usado directamente como librería, seis de los siete módulos enmascaran lo que parece un secreto antes de devolverlo; el decodificador de errores de build no lo hace — cita las líneas coincidentes de tu salida de build tal como están. La redacción tiene límites: consulta lo que no detecta.

Seis de ellos impulsan las herramientas gratuitas en iloveblogs.blog/tools, donde puedes probar cada uno en el navegador.

Módulo	Export principal (dev-error-explainers)	Qué explica	Pruébalo en vivo
cors-error-explainer	diagnoseCors	Errores "bloqueado por política CORS" de Chrome / Firefox / Safari: cabeceras Access-Control-Allow-* faltantes o incorrectas, fallos de preflight, credenciales, contenido mixto — con una solución para tu stack	Explicador de errores CORS
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 — consciente de tu versión de Node.js	Explicador de errores ESM/CJS
npm-eresolve-explainer	analyseEresolveLog	Conflictos de dependencias peer npm ERR! ERESOLVE: quién solicita qué rango, qué está instalado y por qué no se intersectan	Explicador de npm ERESOLVE
chunk-cache-explainer	diagnoseChunkCache	ChunkLoadError / "Loading chunk failed" después de un deploy: lee tus cabeceras de respuesta y encuentra el HTML obsoleto, el acierto de caché del CDN o el fallback del SPA	Comprobador de caché ChunkLoadError
database-url-doctor	diagnoseDatabaseUrl	Cadenas de conexión de Postgres / Supabase: pooler vs directo, puerto 5432 vs 6543, pgbouncer, SSL, caracteres de contraseña sin codificar — con una URL corregida para Prisma, Drizzle, pg o psql	Doctor de DATABASE_URL
build-error-decoder	decodeBuildError	Salida fallida de next build / next dev: bailouts de Suspense, uso dinámico del servidor, window is not defined, desajustes de hidratación, resolución de módulos, falta de memoria en el heap, EADDRINUSE…	Decodificador de errores de build de Next.js
database-connection-explainer	explainDatabaseConnection	"Can't connect to the database" de aplicaciones Node.js en PostgreSQL: ECONNREFUSED (incluyendo ::1 localhost), ETIMEDOUT, ENOTFOUND, Prisma P1000 / P1001 / P1017, password authentication failed, no pg_hba.conf entry, too many clients, certificados autofirmados. Los códigos de red genéricos solo se diagnostican junto a una señal de Postgres	Aún no hay herramienta de navegador — reglas y fuentes

Evidencia: la mayoría de los hallazgos citan la fuente principal contra la que se verificaron. El decodificador de errores de build no tiene URL de fuente principal; sus enlaces apuntan a artículos en el sitio del autor, iloveblogs.blog.

Node.js 20 o posterior. Solo módulos ES.

Uso

Todo está disponible desde la raíz del paquete, y cada módulo también se puede importar por separado:

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)

Devuelve los nombres de los módulos que reconocen text, en un orden fijo, o []. Cada módulo se consulta a través de su propio reconocedor — detect no añade heurísticas propias. Ten en cuenta que chunk-cache-explainer lee las cabeceras de respuesta HTTP (la salida de curl -I), no el mensaje de ChunkLoadError en sí; el mensaje solo lo reconoce build-error-decoder.

Contrato JSON

Cada módulo tiene su propia forma de resultado. diagnose(text) mapea todos ellos a una forma con ids de regla estables, después de redactar la entrada — la forma que la CLI imprime con --json, la GitHub Action renderiza y el servidor MCP devuelve:

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 }] }

La entrada desconocida da { matched: false, results: [] } — nunca una suposición aproximada. La forma, la tabla completa de reglas, la semántica de confianza y los límites de redacción están en docs/CONTRACT.md. Un corpus público de errores reales pegados con sus resultados esperados vive en fixtures/, cada caso con su fuente. redact(text) también se exporta (dev-error-explainers/redact).

CLI

Pasa un comando fallido por tubería, o pasa un archivo de log. No se envía nada a ningún sitio.

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)

Banderas: --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 inicia el servidor MCP.

Códigos de salida: 0 se reconoció un error, 2 no se reconoció nada (no se adivina nada), 64 error de uso. Una cadena de conexión siempre se imprime con su contraseña enmascarada.

Úsalo en CI (GitHub Action)

Cuando un paso falla, la Action lee el log que guardaste de él y escribe la causa y la solución en el resumen del job, con anotaciones en el archivo y la línea cuando el log nombra un archivo en tu checkout. Sin red, sin LLM, sin 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 failure
        if: steps.build.outcome == 'failure'
        uses: mahdibrr/dev-error-explainers@v0
        with:
          log-file: build.log

      - name: Fail the job if the build failed
        if: steps.build.outcome == 'failure'
        run: exit 1                  # …then keep the job red

Entradas, salidas y por qué pipefail y steps.build.outcome importan: docs/ACTION.md.

Úsalo desde tu asistente de IA (MCP)

Un servidor MCP con una herramienta, explain_error, para que un asistente pueda verificar un error pegado contra la causa documentada antes de adivinar. Sin conexión y determinista; la entrada no reconocida se informa como tal. Claude Code:

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

Claude Desktop, Cursor, VS Code y los detalles del protocolo: docs/MCP.md.

Úsalo en Claude Code (plugin: skill + MCP)

El repositorio también es un marketplace de plugins de Claude Code. El plugin incluye el servidor MCP y una skill que le dice a Claude cuándo llamarlo:

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

Principios

• Determinista. La misma entrada siempre da la misma respuesta; las reglas se prueban contra texto de error real (preguntas de Stack Overflow, issues de GitHub, salida de frameworks).
• Sin conexión. No se envía nada a ningún sitio: la entrada nunca sale del proceso.
• Citado cuando es posible. Los hallazgos enlazan a la documentación que establece la regla, cuando existe — no todas las reglas citan una fuente.
• Honesto sobre lo desconocido. Un error que el módulo no reconoce se informa como no reconocido, nunca se adivina.

Pruebas

npm install
npm test

CI ejecuta la suite en Node.js 20, 22 y 24.

Contribuciones

¿Error no reconocido? Abre un issue con el texto exacto. Pega el error tal como se imprimió, el comando que lo produjo y las versiones de las herramientas. Una regla nueva necesita una prueba construida a partir de un error real. Un diagnóstico incorrecto también es un bug — hay una plantilla separada para eso.

Licencia

MIT

Mantenedor y contexto del proyecto

Mantenido por Mahdi Ben Rhouma.

• Notas del proyecto y herramientas de navegador - Cómo la librería sin conexión se conecta a las herramientas de navegador, la CLI y ejemplos públicos.