Dev error explainers

dev-error-explainers

エラーを貼り付けるだけで、確定的な説明が得られます。

LLM 不要・API 不要・ネットワーク不要・テレメトリーなし

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

出力：

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

依存関係ゼロの、小規模で純粋な JavaScript モジュールが 7 つあります。それぞれ、開発者が貼り付けたエラーテキスト（ブラウザーコンソール、npm、next build、curl -I、Node.js のスタックトレースなど）を正確に認識し、発生する理由を説明して、一次情報源がある場合はそのリンク（MDN、Node.js ドキュメント、npm ドキュメント、PostgreSQL ドキュメント、Supabase ドキュメントなど）とともに具体的な修正方法を返します。同じエンジンがライブラリ、CLI、GitHub Action、MCP サーバーとして動作します。

シークレットについて：CLI、Action、MCP サーバーでは、入力を解析する前に redact() を通します。ただし 1 つ例外があります。DATABASE_URL doctor は生の postgres:// の行を読み取ります（パスワードの正確な文字が診断を左右するため）が、そのパスワードを出力することはありません。ライブラリとして直接使用した場合、7 つのモジュールのうち 6 つは、内容を再出力する前にシークレットらしきものをマスクしますが、build-error decoder はマスクしません。ビルド出力の該当行をそのまま引用します。秘匿化には限界があります。検出できないものをご覧ください。

そのうち 6 つは、無料ツール iloveblogs.blog/tools を支えており、ブラウザー上でそれぞれを試せます。

モジュール	メインエクスポート（dev-error-explainers）	説明する内容	ライブで試す
cors-error-explainer	diagnoseCors	Chrome／Firefox／Safari の「CORS ポリシーによってブロックされました」エラー：Access-Control-Allow-* ヘッダーの不足や誤り、プリフライトの失敗、認証情報、混合コンテンツを診断し、使用しているスタックに合わせた修正方法を提示します	CORS Error Explainer
esm-cjs-explainer	explainEsmCjs	ERR_REQUIRE_ESM、「モジュール外では import 文を使用できません」、「ES モジュールのスコープでは exports が定義されていません」、ERR_UNKNOWN_FILE_EXTENSION ".ts"、ERR_MODULE_NOT_FOUND、ERR_PACKAGE_PATH_NOT_EXPORTED を診断します。Node.js のバージョンも考慮します	ESM/CJS Error Explainer
npm-eresolve-explainer	analyseEresolveLog	npm ERR! ERESOLVE のピア依存関係の競合：どのパッケージがどの範囲を要求しているか、何がインストールされているか、範囲が一致しない理由を説明します	npm ERESOLVE Explainer
chunk-cache-explainer	diagnoseChunkCache	デプロイ後の ChunkLoadError／「チャンクの読み込みに失敗しました」：レスポンスヘッダーを読み取り、古い HTML、CDN のキャッシュヒット、SPA フォールバックを特定します	ChunkLoadError Cache Checker
database-url-doctor	diagnoseDatabaseUrl	Postgres／Supabase の接続文字列：プーラーか直接接続か、ポート 5432 か 6543 か、pgbouncer、SSL、エンコードされていないパスワード文字を診断し、Prisma、Drizzle、pg または psql 用の修正済み URL を提示します	DATABASE_URL Doctor
build-error-decoder	decodeBuildError	失敗した next build／next dev の出力：Suspense によるビルド中断、動的サーバー使用、window is not defined、ハイドレーションの不一致、モジュール解決、ヒープメモリ不足、EADDRINUSE などを診断します	Next.js Build Error Decoder
database-connection-explainer	explainDatabaseConnection	PostgreSQL を使用する Node.js アプリの「データベースに接続できません」：ECONNREFUSED（::1 の localhost を含む）、ETIMEDOUT、ENOTFOUND、Prisma の P1000／P1001／P1017、password authentication failed、no pg_hba.conf entry、too many clients、自己署名証明書。一般的なネットワークコードは、Postgres に関するシグナルと併せてのみ診断します	ブラウザツールはまだありません — ルールとソース

エビデンス：調査結果の大半には、照合した一次ソースが引用されています。 build-error decoder には一次ソースの URL がなく、リンク先は作者のサイト iloveblogs.blog の記事です。

Node.js 20 以降。ES モジュールのみ。

使い方

すべてパッケージのルートから利用でき、各モジュールを個別にインポートすることもできます：

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)

text を認識するモジュール名を固定順で返します。該当するものがない場合は [] を返します。 各モジュールには、それぞれ独自の認識器を通じて問い合わせます。detect 自体はヒューリスティックを追加しません。 chunk-cache-explainer が読み取るのは HTTP レスポンスヘッダー（curl -I の出力）であり、ChunkLoadError メッセージそのものではない点に注意してください。メッセージだけを認識するのは build-error-decoder です。

JSON コントラクト

各モジュールはそれぞれ異なる結果形式を持っています。diagnose(text) は入力を秘匿化したうえで、すべての結果を安定したルール ID を持つ単一の形式に統一します。これは、CLI が --json で出力し、GitHub Action が表示し、MCP サーバーが返す形式です。

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

認識できない入力に対しては { matched: false, results: [] } を返し、最も近い候補を推測することはありません。形式、ルール一覧、信頼度の意味、秘匿化の制限については、docs/CONTRACT.md をご覧ください。実際に貼り付けられたエラーと期待される結果をまとめた公開コーパスは fixtures/ にあり、各ケースには出典が付いています。redact(text) もエクスポートされています（dev-error-explainers/redact）。

CLI

失敗したコマンドをパイプで渡すか、ログファイルを指定してください。どこにもデータは送信されません。

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)

フラグ：--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 を実行すると、MCP サーバーが起動します。

終了コード：0 エラーを認識した場合、2 何も認識しなかった場合（推測はしません）、64 使用方法に誤りがある場合。 接続文字列を出力する際は、必ずパスワードをマスクします。

CI での使用（GitHub Action）

ステップが失敗すると、Action は保存されたログを読み取り、原因と修正方法をジョブのサマリーに書き込みます。ログにチェックアウトしたリポジトリ内のファイル名が記載されている場合は、ファイルと行に注釈を付けます。ネットワークも、LLM も、トークンも不要です。

      - 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

入力、出力、そして pipefail と steps.build.outcome が重要な理由： docs/ACTION.md。

AI アシスタントからの使用（MCP）

explain_error というツールを1つ備えた MCP サーバーです。アシスタントは、推測する前に、貼り付けられたエラーを文書化された原因と照合できます。オフラインで決定論的に動作し、認識できない入力はそのように報告されます。Claude Code：

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

Claude Desktop、Cursor、VS Code、およびプロトコルの詳細： docs/MCP.md。

Claude Code での使用（プラグイン：スキル＋MCP）

このリポジトリは Claude Code プラグインのマーケットプレイスでもあります。プラグインには MCP サーバーと、Claude に呼び出すタイミングを指示するスキルが含まれています。

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

原則

• 決定論的。 同じ入力には常に同じ回答を返します。ルールは、実際のエラーテキスト（Stack Overflow の質問、GitHub の issue、フレームワークの出力）を使ってテストされています。
• オフライン。 どこにもデータは送信されず、入力がプロセスの外に出ることはありません。
• 可能な場合は出典を提示。 該当するルールを記載したドキュメントがあれば、調査結果からそのドキュメントにリンクします。すべてのルールに出典があるわけではありません。
• 不明な点を偽らない。 モジュールが認識できないエラーは、推測せず、認識できないものとして報告します。

テスト

npm install
npm test

CI では Node.js 20、22、24 でテストスイートを実行します。

貢献

認識されないエラーがありましたか？正確なテキストを添えてissue を作成してください。 エラーが表示されたとおりのテキスト、エラーを発生させたコマンド、ツールのバージョンを貼り付けてください。新しいルールには、実際のエラーに基づくテストが必要です。診断が誤っている場合もバグです。その報告には専用のテンプレートがあります。

ライセンス

MIT

メンテナーとプロジェクトの背景

Mahdi Ben Rhouma がメンテナンスしています。

• プロジェクトのメモとブラウザーツール - オフラインライブラリがブラウザーツール、CLI、公開サンプルとどのようにつながるかを説明します。