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

Zinnector® CLI で実際に発生するエラー、それぞれの意味、およびその修正方法です。すべての項目に表示される正確なテキストが記載されているため、このページ内を検索できます。該当するエラーがない場合は、失敗したコマンドを ZINNECTOR_DEBUG=1 を付けて実行し、その出力、ご使用の node --version、およびオペレーティングシステムを添えて [github.com/Zinn-Digital/zinnector/issues] (https://github.com/Zinn-Digital/zinnector/issues) で Issue を開いてください。

ランタイムのインストールを承認した直後の "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] (https://nodejs.org/en/download) から最新の 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 (約 30 MB、nodejs.org のチェックサムで検証済み) を取得するため、コンパイルが発生することはありません。アップグレード後もこの問題が発生する場合は、zinnector dev --reset-runtime を実行して、前回の不完全なインストールを一度破棄してください。

クリーンアップ時の npm からの "EPERM" 警告 (Windows)

ほぼすべての場合において、npm がファイルを削除しようとしている最中に、アンチウイルススキャナーまたは検索インデクサーがランタイムの node_modules 内でファイルを開いたままにしていることが原因です。次回の 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 で確認できます。

関連情報

• [Getting started] (/kb/zinnector-getting-started) · [Local development] (/kb/zinnector-local-development) · [Deploying] (/kb/zinnector-deploying) · [Command reference] (/kb/zinnector-command-reference)