症状から対処を探す表です。より詳しい復旧手順は エラーと復旧 を参照してください。ライフサイクルの動作は サンドボックスのライフサイクル を参照してください。
| 症状 | 確認すること |
|---|---|
RuntimeControlProtocolError、デプロイ後の control/protocol 失敗 |
Worker パッケージとコンテナイメージの系統が違っています。同じ @next / cloudflare/sandbox:next（または同じプレリリース）の組み合わせを使います。 |
コンテナが ready にならない、または ContainerUnavailableError が繰り返される |
コールドスタートまたは容量の問題です。retryAfterMs が設定されている場合はそれに従って待ち、そのあと 処理本体 を再試行します。エラーと復旧 を参照してください。 |
wrangler dev では動くが、本番だけ失敗する |
本番だけの制限とコールドスタートです。パッケージとイメージは揃えたままにします。 |
| 症状 | 確認すること |
|---|---|
await exec は「完了」したが、コマンドは動いていない |
exec は 起動時 に解決します。output()、waitForExit()、または exitCode を使います。 |
| stdout が文字列にならない | output() のデフォルトはバイトです。{ encoding: "utf8" } を渡します。 |
getProcess が null / 一覧が [] |
コンテナが動いていないか、現在の コンテナで ID が不明です。探索ではサンドボックスは起きません。必要なら保存したジョブ状態から再起動します。 |
StaleProcessHandleError |
ハンドルは以前のコンテナのものです。チェックポイントした作業から新しい exec を開始します。 |
| 待機がタイムアウト / 中断したが、プロセスは動いている | ローカルの待機だけです。止めたい場合は kill() を呼びます。 |
| ポートが ready にならない | waitForPort のデフォルトモードは TCP です。HTTP の確認には mode: "http" を使います。プロセスが終了していることもあります。ステータスとログを確認します。 |
| 対話的な stdin が必要 | プロセスハンドルでは使えません。ターミナル か、非対話の argv/cwd/env を使います。 |
| 症状 | 確認すること |
|---|---|
ブラウザがまだ sessionId を使っている |
Preview の xterm ヘルパーは terminalId を想定しています。 |
getTerminal が null |
プロセスと同じ寿命ルールです。コンテナが置き換わったら、もう一度作成します。 |
| 再接続で履歴がない | 最後の cursor を connect / 出力オプションに渡します。 |
| 症状 | 確認すること |
|---|---|
以前の exec の環境変数が「消えた」 |
セッションシェルはありません。setEnvVars や起動ごとの env を使います。環境変数 を参照してください。 |
| API キーがコンテナに漏れた | 本番のシークレットをサンドボックスの環境変数に入れないでください。Worker 側の 送信トラフィック ハンドラーを使います。 |
| 症状 | 確認すること |
|---|---|
sandbox.createCodeContext is not a function |
withInterpreter を付け、sandbox.interpreter.* を呼び出します。 |
| Python が使えない | 同じ @next 系統の -python イメージバリアントを使います。 |
| 症状 | 確認すること |
|---|---|
Bridge の /exec、セッション、/pty の動作が @next の Worker SDK ドキュメントと違う |
自分でデプロイした Bridge は 1.0 プレビューの対象外です。安定版パッケージとコンテナイメージに合わせた 安定版 Bridge を使います。 |
@next 上のエージェントと長時間ツールでは、次のようにします。
exec(argv)で起動します（多くの場合['/bin/bash', '-lc', script]）。- 待つときは
waitForLog、waitForPort、またはlogsを使います。await execだけにはしません。 - 永続化するのは ジョブ状態（コマンド、
cwd、env、チェックポイント）です。process.idだけではありません。 - 後続リクエストでは、同じコンテナがまだ保持していれば
getProcess(id)を使い、そうでなければ再度execします。 - ターミナル は人間向けの PTY が必要なときだけ使います。セッションの代わりにはしません。
プロセスの実行、移行、および sandbox-sdk ↗ リポジトリの例（claude-code、codex、opencode など）を参照してください。