GraphQL スキーマを更新するために dotnet graphql update を実行したのに、「graphql が認識されない（not recognised）」と表示されて失敗する。以前は動いていたのに、久しぶりに触ったら突然動かなくなった――そんなときは、StrawberryShake の CLI ツールが環境から外れているケースがほとんどです。原因の見分け方から復旧、再発防止までまとめます。
「graphql が認識されない」とは何が起きているのか
dotnet graphql update は、.NET SDK に最初から付いてくる標準機能ではありません。実体は StrawberryShake の .NET CLI ツール（StrawberryShake.Tools）で、内部的には dotnet-graphql というツール実行ファイルを dotnet が見つけて起動しています。
そのため、ツールが未インストールだったり、ローカルツールの復元がされていなかったり、実行ディレクトリがズレていたりすると、「graphql なんてコマンドは無い」という扱いになります。
| 見えるエラー（例） | 意味 | まず疑うこと |
|---|---|---|
'graphql' is not recognized as an internal or external command | graphql というコマンドが PATH 上に存在しない | dotnet graphql ではなく graphql を打っていないか（打っているなら dotnet 付きに戻す） |
Could not execute because the specified command or file was not found. | dotnet graphql が実体（dotnet-graphql）を見つけられない | StrawberryShake.Tools が入っていない／復元されていない／実行場所が違う |
You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH. | グローバルツールとしても見つからない | グローバルに入っていたのが消えた、または PATH が変わった |
Run "dotnet tool restore" to make the "dotnet-graphql" command available. | ローカルツールのマニフェストはあるが、復元が未実施 | dotnet tool restore を実行する |
原因の本質：dotnet graphql は「NuGet を入れたら常に使える」ものではない
ここが一番の落とし穴です。GraphQL クライアント（StrawberryShake）のプロジェクトに NuGet パッケージを追加していても、CLI コマンドが常に使えるとは限りません。CLI は「.NET ツール」として別枠で管理されます。
| 種類 | 入れる場所 | 役割 | 今回の症状との関係 |
|---|---|---|---|
| NuGet パッケージ（例：StrawberryShake など） | .csproj | アプリ実行時／ビルド時に参照されるライブラリ | 入っていても dotnet graphql が使えるとは限らない |
| .NET CLI ツール（例：StrawberryShake.Tools） | グローバル or ローカル（マニフェスト） | dotnet graphql update などのコマンドを提供 | これが無い／復元されていないと「graphql が認識されない」 |
| ローカルツール マニフェスト | .config/dotnet-tools.json | チームでツールのバージョンを固定・共有する仕組み | 実行ディレクトリがズレるとツールが見つからない |
特にしばらく触っていないプロジェクトで起きやすいのは、次のような変化です。
- PC の買い替え・環境再構築でグローバルツールが入っていない
- リポジトリを clone しただけで
dotnet tool restoreをしていない - マニフェストがあるディレクトリ以外でコマンドを実行している
- SDK の更新やキャッシュ削除で、ツールが実質的に消えたように見える
最短で直す手順：ローカルツールとして StrawberryShake.Tools を復旧する
チーム開発や CI を考えるなら、ローカルツール（マニフェスト管理）で揃えるのが安定です。ここからは「dotnet graphql update を確実に復活させる」ための手順を、チェック順に並べます。
いまどこでコマンドを実行しているか確認する
ローカルツールは マニフェストがある場所（通常はリポジトリのルート配下）で効きます。まずは次を確認してください。
- ソリューション（
.sln）がある階層、またはその配下で実行しているか .configフォルダが見える階層か
例（Windows）：
dir
dir .configツール マニフェスト（dotnet-tools.json）があるか確認する
一般的に、ローカルツールのマニフェストは .config/dotnet-tools.json にあります。存在するか確認します。
dir .config\dotnet-tools.jsonもし無ければ、新規作成します（作業ディレクトリは「プロジェクトの基準にしたい場所」がおすすめです。多くの場合はリポジトリのルートです）。
dotnet new tool-manifestStrawberryShake.Tools をローカルツールとしてインストールする
マニフェストがあるディレクトリで、ローカルツールとしてインストールします。
dotnet tool install --local StrawberryShake.Toolsすでに入っているはずなのに壊れていそう、あるいはバージョンを上げたい場合は更新を試します。
dotnet tool update --local StrawberryShake.Tools逆に、状態が怪しいときは一度アンインストールして入れ直すのが早いこともあります。
dotnet tool uninstall --local StrawberryShake.Tools
dotnet tool install --local StrawberryShake.Toolsマニフェストがあるのに未復元なら dotnet tool restore
リポジトリに .config/dotnet-tools.json がコミットされているタイプのプロジェクトでは、最初にやるべきコマンドはインストールではなく復元です。
dotnet tool restore「以前は動いたのに今は動かない」ケースでも、ローカルツールが未復元の状態になっていることは普通にあります（新しい端末、別のシェル、クリーン環境、CI など）。
コマンドが戻ったか確認する
ヘルプが出れば復旧完了です。
dotnet graphql -h
dotnet graphql update -hここでヘルプが表示されれば、あとは通常通りスキーマ更新を実行できます。
dotnet graphql updatedotnet-tools.json の「見るべきポイント」
ローカルツール運用では、.config/dotnet-tools.json が事実上の「チーム共通のツール定義書」になります。ここが欠けている、あるいは内容がズレていると、環境によって動いたり動かなかったりします。
イメージ（例）：
{
"version": 1,
"isRoot": true,
"tools": {
"strawberryshake.tools": {
"version": "x.y.z",
"commands": [
"dotnet-graphql"
]
}
}
}| 項目 | 意味 | トラブル時の見方 |
|---|---|---|
tools の中に strawberryshake.tools があるか | StrawberryShake の CLI が定義されているか | 無ければ dotnet graphql が見つからないのは当然 |
version（ツールのバージョン） | チームで固定するツールのバージョン | 特定のバージョンで壊れる場合は、ここを上げ下げして切り分け |
commands | 提供されるコマンド名 | dotnet-graphql が無いと dotnet graphql が成立しない |
isRoot | マニフェスト探索の基準 | 複数マニフェスト構成では探索の挙動に影響する |
ポイントは、「NuGet の参照（.csproj）とは別に、ツール（.config/dotnet-tools.json）が揃って初めて dotnet graphql が成立する」という二層構造を意識することです。
実行ディレクトリがズレると再現する：ローカルツールの探索ルール
ローカルツールは、マニフェストがある場所から配下に入ったときだけ有効になります。つまり、次のようなときに「昨日まで動いたのに、今日は動かない」が起こります。
- ターミナルを開いた場所が違う（例：別の作業フォルダ）
- ソリューションルートではなく、単体プロジェクトの外側で実行している
- 複数リポジトリを横断する作業で、別のリポジトリで実行している
迷ったら、いったん「マニフェストがある場所」に移動してから実行してください。
cd （リポジトリのルート）
dotnet tool restore
dotnet graphql updateまた、ローカルツールは dotnet が探索して起動しますが、探索に失敗する状況では「ツールを直接指定して実行する」方法が切り札になります。
dotnet tool run dotnet-graphql -- update（環境によっては -- の付け方が不要な場合もありますが、引数の解釈が混ざるのを避けたいときに有効です。）
「ツールは入れたのにダメ」なときの追加チェック
多くはマニフェスト＋復元で直りますが、それでも認識されない／更新できない場合に備えて、確認ポイントをまとめます。
| 状況 | 確認コマンド | 対処 |
|---|---|---|
| ローカルツール一覧に出てこない | dotnet tool list --local | dotnet tool install --local StrawberryShake.Tools をやり直す（マニフェスト階層で実行） |
| マニフェストはあるが復元されていない | dotnet tool restore | CI でもローカルでも、最初に必ず dotnet tool restore を入れる |
| グローバルに入れていた想定だった | dotnet tool list --global | グローバル運用に寄せるなら dotnet tool install --global StrawberryShake.Tools（ただしチームではズレやすい） |
| SDK の状態が怪しい／複数 SDK が混在 | dotnet --info | global.json で SDK を固定している場合、固定バージョンとツールの相性も確認 |
| プロキシや認証の影響でインストール／復元に失敗 | （エラー内容を確認） | 社内プロキシ環境なら NuGet の設定（NuGet.Config）やフィード認証を見直す |
| ターミナルの種類で挙動が違う気がする | （PowerShell / cmd / Git Bash） | まずは同じシェルで再現性を取る。グローバルツール運用なら新しいシェルの起動も試す |
スキーマ更新そのものを成功させるための実務チェック
dotnet graphql update が認識されるようになった後は、「スキーマが更新されない／失敗する」フェーズに進むことがあります。ここは CLI 消失とは別問題ですが、現場ではセットで詰まりやすいので、最低限のチェックだけ押さえておくと復旧が速くなります。
更新前に確認したいこと
- GraphQL サーバーのエンドポイント URL が変わっていないか（開発環境・ステージング環境など）
- 認証が必要な場合、更新時に必要なヘッダー（トークン）が渡せる状態か
- HTTPS 証明書やローカル開発用の証明書で、通信がブロックされていないか
更新後に確認したいこと
更新が成功すると、プロジェクトのどこかに保持しているスキーマファイル（例：schema.graphql など）が変更されます。さらに、そのスキーマを元にクライアントコード生成が走る構成なら、ビルドや生成によって差分が出ます。
| 確認項目 | 見る場所 | チェックの意図 |
|---|---|---|
| スキーマファイルが更新されたか | リポジトリ内のスキーマ格納先 | サーバー側の変更が手元に降りてきているか |
| 生成コードが更新されたか | 生成先フォルダ（プロジェクトの設定に依存） | クライアントが新スキーマに追従できているか |
| 差分が想定どおりか | Git の diff | 破壊的変更（フィールド削除など）が入っていないかを早期検知 |
「最近 GraphQL クライアント側で問題が出ている」「サーバー側のスキーマが変わった可能性がある」状況では、更新後に diff を読むのが特に重要です。単にエラーが消えるだけでなく、何が変わったか（フィールド名、型、nullable、引数など）を把握してから直すと手戻りが減ります。
再発防止：チーム開発で安定させる運用
この手の「急にコマンドが無い」問題は、個人の PC だけでツールを管理していると再発しがちです。プロジェクト側に寄せてしまうのが一番ラクです。
おすすめ：ローカルツール＋マニフェストをコミットする
.config/dotnet-tools.jsonをリポジトリに含める- README や開発手順に「最初に
dotnet tool restore」を明記する - 必要ならツールのバージョンを固定して「環境差」を消す
「復元」と「復元」が違う点を明文化する
現場で混乱しやすいのがここです。dotnet restore と dotnet tool restore は別物です。
| コマンド | 復元するもの | 今回の問題に効くか |
|---|---|---|
dotnet restore | NuGet パッケージ（ライブラリ参照） | 直接は効かない |
dotnet tool restore | ローカルツール（マニフェストで管理される CLI） | 効く（dotnet graphql 復活の本命） |
手順をスクリプト化して「打ち間違い」を消す
個人差が出ないよう、よく使う流れはスクリプトにすると安定します。たとえば「ツール復元 → スキーマ更新 → ビルド」を 1 本にしておくと、久しぶりに触ったときでも復旧が速いです。
dotnet tool restore
dotnet graphql update
dotnet buildCI を組んでいる場合も同じで、ビルド前に dotnet tool restore を入れておくと、「CI だけ失敗する」「新人の環境だけ動かない」といった事故が減ります。
よくある質問
グローバルツールで入れてもいい？
個人用途なら問題ありません。ですがチーム開発では、メンバーごとにバージョンがズレたり、端末移行で消えたりして再発しやすいので、基本はローカルツール（マニフェスト管理）をおすすめします。どうしてもグローバルで揃えたいなら、バージョンを明示して手順書で統一してください。
dotnet graphql ではなく dotnet-graphql と言われた
環境やメッセージによっては、実体のコマンド名（dotnet-graphql）が案内されることがあります。その場合は、案内どおりに実行するか、ローカルツールなら次の形で確実に動かせます。
dotnet tool run dotnet-graphql -- updateツールを戻したのに、スキーマ更新で別のエラーが出る
その場合は CLI 消失ではなく、接続先 URL、認証、証明書、ネットワーク（プロキシ）など別要因の可能性があります。まずは「ツールが動く状態」になったことを切り分けとして確定させ、次に通信系のエラーとしてログを追うのが近道です。
まとめ：この問題は「コマンドが無い」のではなく「ツールの管理場所がズレた」だけ
dotnet graphql update が「graphql が認識されない」と言ってくると、GraphQL 自体や StrawberryShake の設定を疑いたくなりますが、原因の多くはシンプルです。StrawberryShake.Tools（.NET CLI ツール）が入っていない／復元されていない／実行場所が違うだけです。
まずは .config/dotnet-tools.json の有無を確認し、ローカルツール運用なら dotnet tool restore、必要なら dotnet tool install --local StrawberryShake.Tools。ここまで整えば、スキーマ更新の土台が戻り、サーバー側の変更点に集中できるようになります。
コメント