MENU

通常のSSHは通るのにVS Code Remote SSHが接続準備中で止まるときの対処法

Visual Studio

通常のSSHコマンドでは接続できるのに、Visual Studio CodeのRemote SSHでは「接続を準備しています」「接続準備中」などの表示から進まないことがあります。

この場合、ネットワークやSSH鍵そのものではなく、認証入力が画面の裏で待機している、VS Code Serverの起動に失敗している、SSHのポート転送が制限されているといった原因が考えられます。

まずはremote.SSH.showLoginTerminalを有効にして隠れた入力待ちを確認し、改善しなければremote.SSH.useLocalServerをfalseにして再接続します。その後、Remote SSHのログを保存し、必要に応じてリモート側のVS Code Serverを整理するのが効率的です。

ITtripTOOLS
その「面倒」、無料で解決。 ITtripがつくる、6つの道具。 無料ツール一覧へ すべて無料・追加課金なし
先頭0を守るCSV編集こわさないCSV PDFに直接書き込みかけるPDF 写真＋説明をPDFに写レポ スマホ⇄PCで共有コピペ便 · 文章・写真 みんなの日程を調整日程Fit 匿名質問・投票を集めるKOEQ
目次

通常のSSHは通るのにVS Code Remote SSHだけ止まる理由

ターミナルから次のように接続できても、Remote SSHの接続成功までは保証されません。

ssh server-name

通常のSSHでは、サーバーへログインしてシェルを表示できれば接続成功です。

一方、VS Code Remote SSHはログイン後に、リモート側でVS Code Serverを準備し、ローカルのVS Codeと通信するためのSSHトンネルを確立します。そのため、ログイン自体は成功していても、後続処理で止まることがあります。([Visual Studio Code][1])

確認対象通常のSSHVS Code Remote SSH
SSHサーバーへのログイン必要必要
パスワード・秘密鍵の認証必要必要
VS Code Serverの起動不要必要
SSHトンネルの確立通常は不要必要
リモート拡張機能の起動不要必要
VS Code固有の設定影響しない影響する

したがって、「SSHが通るからサーバー側に問題はない」と判断するのは早すぎます。Remote SSHのログを確認し、どの段階で処理が止まっているかを切り分ける必要があります。

最初に試すべき解決手順

接続準備中で止まる場合は、次の順序で確認します。

順番作業判断できること
1リモート作業を保存する後続の再起動や切断に備える
2同じ接続先をSSHコマンドで確認する接続先、ユーザー、SSH設定の基本確認
3showLoginTerminalを有効にする隠れた認証入力を確認する
4useLocalServerをfalseにするローカル側の接続処理を切り替える
5Remote SSHのログを保存するエラー箇所を特定する
6VS Code Serverを整理する壊れたサーバー環境を再作成する
7転送制限を管理者へ確認するサーバー側ポリシーの問題を確認する

設定やサーバーを変更する前に、リモートターミナルで実行中の処理、デバッグ、ビルド、未保存ファイルがないか確認してください。

showLoginTerminalで隠れた認証入力を表示する

Remote SSHが止まっているように見えても、実際には次の入力を待っていることがあります。

  • SSHパスワード
  • 秘密鍵のパスフレーズ
  • ワンタイムパスワード
  • 多要素認証の確認コード
  • 認証システムが表示する追加質問

認証画面が表に出ていないと、ユーザーには単に「接続準備中のまま止まった」ように見えます。

設定画面から有効にする

VS Codeの設定を開き、検索欄に次を入力します。

remote.SSH.showLoginTerminal

「Remote › SSH: Show Login Terminal」を有効にしてから、もう一度接続してください。

settings.jsonで設定する

コマンドパレットを開き、次のコマンドを実行します。

Preferences: Open User Settings (JSON)

settings.jsonへ次の設定を追加します。

{
  "remote.SSH.showLoginTerminal": true
}

すでにほかの設定がある場合は、既存の波括弧内へ追加します。前の項目との間にカンマが必要です。

Microsoftの公式トラブルシューティングでも、接続が停止する場合はremote.SSH.showLoginTerminalを有効にし、パスワードやトークンなどの入力待ちが発生していないか確認する方法が案内されています。([Visual Studio Code][1])

ログインターミナルが表示された後の判断

ターミナルが表示されたら、末尾のメッセージを確認します。

認証情報を求められている場合は、内容を確認して入力します。入力後に接続できれば、原因は認証画面が見えていなかったことです。

何も求められず処理が止まる場合は、次のuseLocalServerを確認します。

useLocalServerをfalseにして接続方法を比較する

remote.SSH.useLocalServerは、Remote SSHの接続処理にローカルサーバー方式を使用するかどうかを制御する設定です。

接続が止まる場合は、現在の設定を記録したうえで、明示的にfalseへ変更して再接続します。

{
  "remote.SSH.showLoginTerminal": true,
  "remote.SSH.useLocalServer": false
}

公式ドキュメントでも、showLoginTerminalを有効にしても解決しない場合の切り分けとして、この2つの設定を組み合わせて再試行する方法が案内されています。([Visual Studio Code][1])

設定変更後の再接続手順

  1. settings.jsonを保存します。
  2. 接続中のRemote SSHウィンドウを閉じます。
  3. 新しいVS Codeウィンドウを開きます。
  4. Remote-SSH: Connect to Host...を実行します。
  5. 同じ接続先を選択します。
  6. ログインターミナルと出力ログを確認します。

改善しなかった場合は、useLocalServerの元の値へ戻した状態でも接続し、ログの違いを比較します。

trueとfalseのどちらが常に正しいというわけではありません。重要なのは、一度に多数の設定を変更せず、接続方式を変えたときにエラー箇所が変化するか確認することです。

SSHコマンドとVS Codeが同じ接続設定を使っているか確認する

「通常のSSHは通る」という確認が、Remote SSHと異なる条件で行われているケースもあります。

たとえば、次のような違いです。

  • SSHコマンドではIPアドレスを指定し、VS Codeではホスト名を指定している
  • 異なるユーザー名で接続している
  • 別のSSH設定ファイルを使用している
  • 別の秘密鍵が選択されている
  • 踏み台サーバーの設定が片方にしかない
  • Windows OpenSSHとGit BashのSSHを使い分けている

まず、VS Codeで選択しているホスト名と同じ名前を使って確認します。

ssh my-server

SSH設定が正しく反映されているか詳しく確認する場合は、詳細ログを表示します。

ssh -v my-server

秘密鍵の内容やパスフレーズが表示されるわけではありませんが、ホスト名、ユーザー名、ファイルパス、IPアドレスなどの内部情報が含まれる可能性があります。ログを第三者へ共有するときは必ず確認してください。

VS Code側で特定のSSH設定ファイルを指定している場合は、remote.SSH.configFileの値も確認します。Remote SSHでは、使用するSSH設定ファイルをユーザー設定から明示できます。([Visual Studio Code][2])

Remote SSHのログを保存して停止箇所を確認する

設定を何度も変更する前に、エラーが再現したときのログを保存します。

ログの表示方法

VS Codeで「表示」から「出力」を開き、出力チャンネルの一覧から次を選択します。

Remote - SSH

Remote SSHは接続処理の詳細を、この出力チャンネルへ記録します。([Visual Studio Code][2])

接続を開始する前に出力欄を開いておくと、SSHコマンドの実行からVS Code Serverの起動までを追いやすくなります。

保存しておきたい情報

問い合わせや管理者への連絡に備え、次の情報を記録します。

  • 接続を試した日時
  • ローカルOS
  • VS Codeのバージョン
  • Remote SSH拡張機能のバージョン
  • 接続に使用したホスト名またはホスト別名
  • showLoginTerminalとuseLocalServerの設定値
  • 最初に表示されたエラー
  • エラー直前から直後までのログ

末尾のエラーだけでは原因が分からない場合があります。可能であれば、接続開始からエラー発生までをまとめて保存してください。

ログを共有するときに削除する情報

次の情報は、社外の掲示板や公開リポジトリへそのまま掲載しないでください。

  • ユーザー名
  • グローバルIPアドレス
  • 社内ホスト名
  • ファイルサーバーのパス
  • 秘密鍵
  • パスワード
  • アクセストークン
  • 回復キー
  • ワンタイムパスワード
  • 組織名やプロジェクト名

秘密鍵やトークンが含まれてしまった場合は、文字を隠すだけでなく、漏えいした可能性を前提に失効や再発行を検討します。

ログから原因を判断する

よくあるログと確認先は次のとおりです。

ログや状態主な確認先
パスワードやコードの入力待ちshowLoginTerminal
秘密鍵のパスフレーズ入力待ちSSH Agent、秘密鍵設定
VS Code Server failed to startリモート側のVS Code Server
administratively prohibitedSSHサーバーの転送制限
Permission deniedユーザー、鍵、ファイル権限
No space left on deviceディスク容量、ユーザー容量制限
ダウンロード処理で停止プロキシ、外部接続制限
サーバー起動後に通信できないSSHトンネル、転送設定

エラー文字列を検索する場合は、ホスト名やユーザー名を除き、特徴的な部分だけを使用します。

Kill VS Code Server on Hostでリモート側を整理する

認証とSSHトンネルに問題が見つからず、ログにVS Code Serverの起動失敗が記録されている場合は、リモート側のVS Code Serverを整理します。

コマンドパレットを開き、次を実行します。

Remote-SSH: Kill VS Code Server on Host...

対象のホストを選択して処理を実行した後、もう一度Remote SSHで接続します。

このコマンドは、Remote SSHに関するさまざまな起動エラーを解消するための一般的なトラブルシューティングとして、公式ドキュメントでも案内されています。([Visual Studio Code][1])

実行前に必ず確認すること

VS Code Serverを停止すると、次の処理へ影響する可能性があります。

  • 接続中のRemote SSHウィンドウ
  • VS Codeから起動したタスク
  • デバッグセッション
  • リモート拡張機能
  • 統合ターミナル上の処理
  • 同じアカウントを使っている別の利用者の接続

実行前に、未保存ファイルを保存してください。共有アカウントや共同作業環境では、ほかの利用者へ周知してから実施します。

また、原因調査が必要な場合は、先にRemote SSHのログを保存します。サーバーを整理した後では、障害発生時の状態を確認しにくくなることがあります。

手作業でフォルダーを削除する前にコマンドを使う

リモート側の.vscode-serverなどを手作業で削除する方法も見かけますが、最初から手動削除する必要はありません。

まずはVS Codeが用意しているKill VS Code Server on Host...を使用します。手動削除は、公式コマンドが失敗し、削除対象を正確に判断できる場合に限るのが安全です。

administratively prohibitedは管理者へ確認する

Remote SSHのログに次のエラーが表示された場合は、SSHサーバー側でポート転送が禁止されている可能性があります。

open failed: administratively prohibited: open failed

Remote SSHは、ローカルのVS Codeとリモート側のVS Code Serverを通信させるためにSSHトンネルを使用します。SSHログインだけが許可され、ポート転送が禁止されている環境では、通常のSSHには成功してもRemote SSHは接続できません。([Visual Studio Code][1])

利用者側で無断変更しない

このエラーが表示されても、次の設定を利用者の判断で変更してはいけません。

AllowTcpForwarding

AllowTcpForwardingはSSHサーバー全体のセキュリティポリシーに関係します。組織の方針により、意図的に禁止されている可能性があります。

設定変更、SSHサービスの再起動、ファイアウォール変更は、必ずサーバー管理者の承認を得て実施します。

管理者へ伝える内容

次のように連絡すると、状況が伝わりやすくなります。

通常のSSHログインには成功しますが、VS Code Remote SSHで接続すると、
Remote - SSHログに次のエラーが表示されます。

open failed: administratively prohibited: open failed

対象ユーザーに対するTCP転送の有効設定と、
AllowTcpForwarding、DisableForwarding、PermitOpen、
Matchブロックによる個別制限をご確認ください。

OpenSSHでは、AllowTcpForwarding以外にも、DisableForwardingやPermitOpen、ユーザー・グループ別のMatchブロックによって転送が制限されることがあります。表面上の設定だけでなく、対象ユーザーへ最終的に適用される設定の確認が必要です。([OpenBSD Manual Pages][3])

管理者が確認する主な設定ファイル

代表的な設定ファイルは次のとおりです。

Linux:
/etc/ssh/sshd_config

Windows OpenSSH:
C:\ProgramData\ssh\sshd_config

Microsoftのトラブルシューティングでは、管理方針上問題がない場合の設定例として、次の値が案内されています。

AllowTcpForwarding yes

ただし、この値を採用できるかどうかは、組織のセキュリティ基準によって異なります。設定変更後のSSHサービス再起動も、保守手順や影響範囲を確認してから実施してください。([Visual Studio Code][1])

それでも接続準備中から進まない場合の確認項目

基本手順で改善しない場合は、Remote SSHのログに対応する項目だけを確認します。

リモート側から必要な接続先へアクセスできない

VS Code Serverや拡張機能の準備時に、リモートサーバーから外部へ接続することがあります。

プロキシ環境やインターネット接続を制限した環境では、ダウンロード処理が止まる可能性があります。公式ドキュメントでも、リモートホストのインターネット接続やHTTP_PROXY、HTTPS_PROXYの確認が案内されています。([Visual Studio Code][1])

ただし、認証付きプロキシのパスワードを設定ファイルへ平文で保存するのは避けてください。組織のプロキシ設定手順に従います。

一時フォルダーでプログラムを実行できない

セキュリティ対策として、リモートサーバーの/tmpがnoexecでマウントされていることがあります。

VS Code Serverの準備処理が一時フォルダー上のスクリプトを実行しようとすると、ここで失敗する可能性があります。この場合も制限を無断解除せず、ログと利用目的を添えて管理者へ相談します。([Visual Studio Code][1])

シェルの起動設定が接続処理を妨げている

.bash_profileや.bashrcなどで別のシェルを強制起動したり、ログイン時に対話入力を求めたりすると、VS Code Serverのインストール処理を妨げる場合があります。

ログイン時にメニュー、確認質問、独自コマンドなどを自動実行している場合は、非対話接続でも動作していないか確認します。

WindowsのSSHホストとして正しく認識されていない

接続先がWindowsの場合は、Remote SSHがリモートOSを正しく判定できているか確認します。

必要に応じて、ホストごとのプラットフォームを設定できます。

{
  "remote.SSH.remotePlatform": {
    "windows-server": "windows"
  }
}

ホスト名には、SSH設定ファイルで定義したHost名を指定します。OSを誤って指定すると別の問題が発生するため、実際の接続先がWindowsであることを確認してから設定してください。([Visual Studio Code][1])

接続トラブルで避けたい対応

複数の設定を一度に変える

SSH鍵、SSH設定ファイル、Remote SSH設定、サーバー設定を同時に変更すると、何が原因だったのか分からなくなります。

まずshowLoginTerminal、次にuseLocalServer、その後にVS Code Serverの整理という順番で進めます。

ログを保存する前にサーバーを削除する

サーバーを整理して直ったとしても、再発時の判断材料が残りません。

少なくとも最初に表示されたエラーと、その前後のログを保存してから作業します。

通常のSSH成功だけでサーバー側を除外する

SSHログインの成功と、ポート転送の許可は別の条件です。

administratively prohibitedが表示されている場合、パスワードや秘密鍵を作り直しても解決しません。

SSHサーバーの制限を無断で解除する

AllowTcpForwardingなどの制限には、組織としてのセキュリティ上の理由がある可能性があります。

Remote SSHを利用する必要性、対象ユーザー、対象サーバー、利用期間を整理し、管理者へ正式に確認します。

エラー画面を加工せず公開する

スクリーンショットやログには、社内ホスト名、IPアドレス、ユーザー名、ファイルパスが含まれることがあります。

秘密鍵、回復キー、トークン、ワンタイムパスワードは、画像へ絶対に含めないでください。

接続準備中で止まったときの最終チェックリスト

次の順番で実行すれば、原因を切り分けやすくなります。

  • リモート側の作業と未保存ファイルを保存する
  • VS Codeと同じホスト名で通常のSSH接続を確認する
  • remote.SSH.showLoginTerminalをtrueにする
  • 表示されたパスワード、パスフレーズ、認証コードの入力待ちを確認する
  • remote.SSH.useLocalServerをfalseにして再接続する
  • 出力チャンネルのRemote - SSHログを保存する
  • ログ保存後にRemote-SSH: Kill VS Code Server on Host...を実行する
  • administratively prohibitedがあれば管理者へ転送制限を確認する
  • エラー内容に応じてプロキシ、ディスク容量、一時フォルダー、シェル設定を調べる

通常のSSHが通る場合は、接続先へ到達できている可能性が高いため、闇雲にSSH鍵を作り直すのではなく、認証入力、VS Code Server、SSHトンネルの順に確認することが重要です。

最初にshowLoginTerminalで隠れた入力を表示し、useLocalServerを比較します。そのうえでログを保存し、VS Code Serverの整理や管理者への確認へ進めると、作業への影響を抑えながら原因を特定できます。
[1]: https://code.visualstudio.com/docs/remote/troubleshooting “Remote Development Tips and Tricks”
[2]: https://code.visualstudio.com/docs/remote/ssh “Remote Development using SSH”
[3]: https://man.openbsd.org/sshd_config?utm_source=chatgpt.com “sshd_config(5) – OpenBSD manual pages”

Visual Studio
SSH Visual Studio Code リモート開発 Remote SSH

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次