プレビューやブラウザが表示されない

ブラウザペイン・軽量プレビュー・プレビュー用サブドメインで、アプリが表示されない、更新されない、サインインできないときに、原因と直し方を探せます。 それぞれの使い方は プレビューとブラウザ にあります。

ブラウザペインが target-unreachable になる

ブラウザは起動しましたが、そのポートとパスがまだ応答していません。開発サーバーの起動を待っている間も、こう出ます。

1. ポート番号とパスを確かめます
2. 「再読み込み」を押します
3. それでも残るなら「再接続」を押します

アプリは 127.0.0.1（localhost）で待ち受けていれば届きます。ペインのほかの状態は 起動した Web アプリを見る にあります。

軽量プレビューやプレビュー用サブドメインが 502 のページを出す

ページに、何が起きたかが書かれています。ページはブラウザの言語（日本語か英語）で出ます。

ページの文	やること
「ワークスペース内のポート N で待ち受けているものがありません。…」	アプリを起動してから再読み込みする
「ポート N は待ち受けていますが HTTP を話しません。…」	データベースや SSH などはプレビューできない。プレビューは HTTP と WebSocket だけ
「ポート N は HTTPS で動いています。…」	開発サーバーの HTTPS を無効にする
「ワークスペースが起動していないか、到達できません。」	ワークスペースを起動する

ブラウザペインはアプリに直接つなぐので、このページは出ません。失敗はペインの target-unreachable で出ます。

真っ白になる・404 になる

/static/... のような絶対パスでファイルを読むアプリを、軽量プレビューで開いたときによく起きます。軽量プレビューの URL は /preview/{ポート}/ というサブパスだからです。

• プレビュー用サブドメインが使える環境なら、そちらで開きます
• 使えないなら、「ペインで開く」でブラウザペインに切り替えます

アプリの側の直し方は 起動した Web アプリを見る にあります。

同僚に渡したプレビューの URL が 404 になる

原因	やること
プレビュー用サブドメインの URL は、ワークスペースを起動し直すたびに変わる	プレビューのポップオーバーの「共有」で出るリンクを渡す。起動し直しても使える
「同じテナントのメンバーに見せる」がオフ	⚙設定 →「プレビュー用サブドメイン」でオンにする。オフにすると、相手が開いていても次の操作から見えなくなる
相手の「共有されているプレビュー」に「停止中」と出る	あなたのワークスペースが止まっている。相手は起動できないので、起動してから知らせる
そのポートを設定の一覧から外した	一覧に戻す

自動で更新されない・枠だけ出てデータが出ない

症状	原因とやること
Next.js（15.2 以降）をプレビュー用サブドメインで開くと、レイアウトの枠だけ出て、データの行がひとつも出ない	開発サーバーが別のオリジンからの /_next/* を既定で断っている。ログに ⚠ Blocked cross-origin request to Next.js dev resource が出る。next.config.ts の allowedDevOrigins にワイルドカードを足す
更新されず、ページごと再読み込みされる	通信のない WebSocket が途中で閉じられている
HMR がつながらない	開発サーバーが接続先のポートをクライアントに埋め込んでいることがある。server.hmr.clientPort: 443 のような設定を足す

軽量プレビューとプレビュー用サブドメインは、WebSocket と SSE を通します。設定の書き方は プレビュー用のサブドメインを使う にあります。

設定を足したくないときや、原因を切り分けたいときは「ペインで開く」を使います。ブラウザペインはワークスペースの中のブラウザが 127.0.0.1 を直接開くので、HMR も WebSocket も SSE も、ふつうの localhost と同じように動きます。

プレビューで API が全部 401（preview requires sign-in）になる

• 開発サーバーのプロキシの転送先を、プレビューの URL に書き換えていないか確かめます。 Vite の server.proxy の target や、Next.js の rewrites() の destination は http://127.0.0.1:8080 のままにします。プロキシはワークスペースの中から出る通信なので、ブラウザのサインインを持っていません
• ブラウザから 8080 の URL を直接呼んでいるなら、ポートごとにサインインが要ります。https://＜ランダム＞-8080.… を一度タブで開いて、サインインを通してください。3000 の画面から 8080 を呼ぶ構成なら、⚙設定 →「プレビュー用サブドメイン」の「ポート間の呼び出しを許可する」もオンにします（既定ではオフです）

ブラウザペインが crashed や disconnected になる・何度も落ちる

状態	やること
disconnected	通信が切れただけのことが多い。ワークスペースが動いているか確かめて「再接続」を押す
crashed	ワークスペースの中のブラウザが落ちた。「再接続」で開き直す
短い間に何度も落ちる	メモリが足りない。重いビルドや watcher、開いたままのブラウザペイン（同時に 2 つまで）を減らす

メモリの使い方は マシンと使用状況を見る で確かめられます。

プレビューの URL でサインインすると、Agent Fleet のエラー画面が出る

アプリから開発用のサインイン（OIDC）を使ったときに出る画面です。使い方は プレビューで Google ログインを試す にあります。

画面	原因とやること
「サインインを開始できません」	要求が断られた。アプリに設定したクライアント ID とコールバック URL がこのワークスペースのものか確かめ、アプリからもう一度サインインする
「戻り先のアドレスが許可されていません」	コールバック URL が、このワークスペースのいまのプレビュー URL でも http://localhost:<ポート> でもない。アプリ側で直して、もう一度サインインする
「サインインの確認が無効です」	確認が断られたか、期限が切れたか、すでに使われた。アプリからもう一度サインインする
「サインインを完了できません」	サーバー側の問題。少し待ってから試し、続くならこの配備の管理者に連絡する
「アプリからサインインしてください」	サインインの途中の画面だけを開いている。プレビュー中のアプリから始める

プレビューの URL が、ポートが変わった・ポートが多すぎる・再起動が要ると言う

アプリではなく、プレビューが出しているメッセージです。

メッセージ	やること
「ポート N の待ち受けが変わったか停止しました。Console からもう一度開いてください。」	そのポートのサーバーが再起動したか、入れ替わった。Console のポートのチップかプレビューから開き直す
「一時的に開いているポートが多すぎます。サーバーを止めるか、設定のプレビューポートに追加してください。」	要らなくなったサーバーを止めるか、⚙設定 →「プレビュー用サブドメイン」にそのポートを登録する
「ポート N を開くには、ワークスペースの再起動が必要です（Agent がこの機能より古い版です）。」	ワークスペースを再起動する

関連

• プレビューとブラウザ
• マシンと使用状況を見る