Zinnector® のトラブルシューティング

Zinnector® CLIで実際に発生するエラー、それぞれの意味、そしてその修復方法について説明します。すべての項目に確認できる正確なテキストが記載されているため、このページ内を検索することができます。もし該当するエラーが見つからない場合は、失敗したコマンドを ZINNECTOR_DEBUG=1 を指定して実行し、その出力、お使いの node --version、およびオペレーティングシステムを添えて、github.com/Zinn-Digital/zinnector/issues にIssuesを作成してください。

ランタイムのインストール承諾直後の "spawn EINVAL"（Windows）

Zinnector® 0.1.0および0.1.1におけるバグです。Windowsでは、ランタイムインストーラーが npm.cmd を名前で実行していましたが、NodeはCVE-2024-27980の修正以降、シェルなしで .cmd ファイルの起動を拒否するようになったため、Y と回答した1秒後にインストールがクラッシュしていました。0.1.2で修正済み: npmは現在 node npm-cli.js として実行されるため、すべてのプラットフォームで共通となり、シェルは不要です。npm install -g zinnector@latest を実行してから、再度 zinnector dev を実行してください。

インストール中の "npm WARN EBADENGINE"、または "Zinnector® needs Node 24 or newer"

お使いのNodeのバージョンが24よりも古いです。パッケージが engines: >=24.18.1 を宣言しているためnpmが警告を表示しますが、インストール自体は完了します。ただし、後で分かりにくい場所で失敗するのを防ぐため、その後 zinnector の起動が拒否されます（終了コード78）。nodejs.org から現在のLTSをインストールし（Windowsの場合は winget install OpenJS.NodeJS.LTS、macOSの場合は brew install node@24）、node --version が v24 以上を出力することを確認してから、再度 Zinnector® をインストールしてください。

"gyp ERR!", "Building from source with node-gyp", または "You need to install Visual Studio"

WordPressランタイムには、Node 24および25用の事前ビルド済みバイナリのみが存在するネイティブモジュールが含まれています。より新しいNode（2026年9月時点のバージョン26以降）では、インストーラーがソースからのコンパイルにフォールバックするため、通常のWindowsマシンではVisual Studioのインストールを要求されて終了します。0.1.2で修正済み: Zinnector®は何もダウンロードする前にこれを検出し、ランタイム専用のNode 24（nodejs.orgのチェックサムで検証済みの約30MB）を取得するため、何もコンパイルされることはありません。アップグレード後もこのエラーが表示される場合は、zinnector dev --reset-runtime を実行して、以前の途中で中断されたインストールを最初に破棄してください。

クリーンアップ中のnpmによる "EPERM" 警告（Windows）

ほとんどの場合、ランタイムの node_modules 内にあるファイルを、npmが削除しようとしている最中に、アンチウイルススキャナーや検索インデクサーが保持していることが原因です。次回の zinnector dev 実行時に、クリーンなディレクトリからのインストールが再試行されます。それでも発生する場合は、zinnector dev --reset-runtime により、最初にランタイムディレクトリ全体が削除されてから再度インストールされます。

"the local playground runtime could not be installed"

このメッセージには、npm自体の最後の数行と、Zinnector®が実行した正確なコマンドが含まれているため、ご自身で実行してすべての出力を確認することができます。一般的な原因は、ネットワークやプロキシの問題（ランタイムはご自身のnpmを使用して取得されるため、npm config set proxy … やレジストリミラーが適用されます）、または --reset-runtime でクリアされる、以前の途中で中断されたインストールです。

"the local playground exited before it was ready"、または準備完了にならない

ランタイム自体の出力を確認するには、zinnector dev --verbose を実行してください。ポートがすでに使用されていることが一般的な原因です：zinnector dev --port 9401 を実行するか、zinnector.json で port を設定してください。インストールは完了したものの起動しない場合は、zinnector dev --reset-runtime を実行してください。最初の起動時にはWordPress自体もダウンロードされるため、低速な接続の場合は数分お待ちください。CLIはハングアップする代わりに、タイムアウトを報告するまで最大5分間待機します。

プッシュ時の "this project is not a git repository"

デプロイはリポジトリから実行されるため、zinnector push には、プラットフォームがアクセスできるリモートリポジトリを持つリポジトリが必要です。git init && git add -A && git commit -m initial を実行し、GitHubまたはGitLabのリモートを追加してから、zinnector link を実行してサイトに接続してください。

デプロイ後にサイトが白紙になる

zinnector check を実行してください。10回中9回はPHPのバージョンのギャップが原因であり（スロットが実行しているものよりも新しいPHPでビルドされています）、どのバージョンにスロットを切り替えるべきか（zinnector php <version>）、あるいはどのバージョンに対して開発すべきか（zinnector dev --php <version>）がレポートに示されます。zinnector logs --error で致命的なエラーそのものを確認できます。