Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

エラー

最終更新 Markdown で表示Agent セットアップ

Sandbox SDK 1.0 プレビューが返すエラークラスとコード、短い推奨対処です。回復手順の全体は エラーと回復 を参照してください。

エラーの返され方

操作は、catch できる例外を投げます。@cloudflare/sandbox のクラスに対する instanceof を優先してください。メトリクスと安定したフィールド参照には code と context を使います。

import {
	ContainerUnavailableError,
	OperationInterruptedError,
	RPCTransportError,
} from "@cloudflare/sandbox";

try {
	await sandbox.exec(["npm", "test"], { cwd: "/workspace/app" });
} catch (error) {
	if (error instanceof ContainerUnavailableError) {
		// error.code === "CONTAINER_UNAVAILABLE"
		// error.context.reason, error.context.retryAfterMs
	}
	if (error instanceof OperationInterruptedError) {
		// Convenience getters: error.reason, error.retryable, error.operationName
		// admitted is only on context: error.context.admitted
	}
	if (error instanceof RPCTransportError) {
		// Convenience getters: error.kind, error.originalMessage
	}
}
import {
	ContainerUnavailableError,
	OperationInterruptedError,
	RPCTransportError,
} from "@cloudflare/sandbox";

try {
	await sandbox.exec(["npm", "test"], { cwd: "/workspace/app" });
} catch (error) {
	if (error instanceof ContainerUnavailableError) {
		// error.code === "CONTAINER_UNAVAILABLE"
		// error.context.reason, error.context.retryAfterMs
	}
	if (error instanceof OperationInterruptedError) {
		// Convenience getters: error.reason, error.retryable, error.operationName
		// admitted is only on context: error.context.admitted
	}
	if (error instanceof RPCTransportError) {
		// Convenience getters: error.kind, error.originalMessage
	}
}

インポート

よく使うライフサイクル、プロセス、ターミナル、バックアップのエラーは、パッケージルートから利用できます。

import {
	ContainerUnavailableError,
	OperationInterruptedError,
	RPCTransportError,
	StaleProcessHandleError,
	// ...
} from "@cloudflare/sandbox";
import {
	ContainerUnavailableError,
	OperationInterruptedError,
	RPCTransportError,
	StaleProcessHandleError,
	// ...
} from "@cloudflare/sandbox";

完全なモジュールは、ErrorCode、SandboxError、createErrorFromResponse、その他のドメインエラー（ファイル、ポート、インタープリター、マウント、関連する context 型）もエクスポートします。

import {
	ErrorCode,
	SandboxError,
	createErrorFromResponse,
	FileNotFoundError,
	// ...
} from "@cloudflare/sandbox/errors";
import {
	ErrorCode,
	SandboxError,
	createErrorFromResponse,
	FileNotFoundError,
	// ...
} from "@cloudflare/sandbox/errors";

プラットフォームヘルパー（SandboxError のサブクラスではありません）:

import {
	isPlatformTransientError,
	isDurableObjectCodeUpdateReset,
} from "@cloudflare/sandbox";
import {
	isPlatformTransientError,
	isDurableObjectCodeUpdateReset,
} from "@cloudflare/sandbox";

SandboxError の形

ほとんどの SDK エラーは SandboxError を継承します。

メンバー 説明
name クラス名（例: ContainerUnavailableError）
message 人が読めるメッセージ
code 安定した ErrorCode 文字列（例: CONTAINER_UNAVAILABLE）
context エラータイプごとの構造化フィールド
httpStatus 該当する場合に対応する HTTP ステータス
operation 指定された場合の操作ラベル
suggestion 任意の対処提案
timestamp 指定された場合の ISO タイムスタンプ
toJSON() ログ用にエラーフィールドをシリアライズします

RuntimeIdentityInactiveError は Error を直接継承します（SandboxError ではありません）。現在のコンテナーが、このハンドルまたは呼び出しのアクティブなコンテナーではなくなったことを意味します。

表には 推奨する対処 列があります。長い回復手順は エラーと回復 を参照してください。

可用性エラーとデプロイ不一致エラーは、別の節に分けています。両方に同じ再試行ループを使わないでください。

コンテナーの可用性と中断された呼び出し

これらのエラーは、通常の起動、アイドル停止、置き換え、または呼び出し実行中の切断から発生します。

クラス コード 主要な context 詳細 推奨する対処
ContainerUnavailableError CONTAINER_UNAVAILABLE reason、retryable: true、retryAfterMs? 操作開始前にコンテナーの準備ができていません。 バックオフします（設定されている場合は retryAfterMs を守ります）。その後、同じ種類の処理を再試行します。
OperationInterruptedError OPERATION_INTERRUPTED reason、operation、admitted、retryable 操作が開始したあとに、コンテナーまたはサンドボックスが変わりました。 reason と retryable を確認します。状態を変える処理を繰り返す前に、サンドボックスまたはアプリの状態を確認します。
RPCTransportError RPC_TRANSPORT_ERROR kind、originalMessage、errorName、closeCode? 呼び出し中に SDK がコンテナーとの接続を失いました。 後続の呼び出しは成功することがあります。この呼び出しは、すでに何かを変更している可能性があります。
RuntimeIdentityInactiveError — — 現在のコンテナーは、この呼び出しまたはハンドルではアクティブではありません。通常の Error であり、SandboxError ではありません。 リソースがまだ存在するかを確認します。存在しなければ、保存済みの状態から作業をやり直します。

ContainerUnavailableError の reason

context.reason:

Reason 意味
container_starting コンテナーはまだ起動中です
container_unhealthy コンテナーは健全ではありません
container_replaced コンテナーが置き換えられました
rpc_upgrade_failed コンテナーとの通信を確立できませんでした

OperationInterruptedError の reason

reason / context.reason:

Reason 意味
runtime_replaced 背後のコンテナーインスタンスが置き換えられました
container_stopped コンテナーが停止しました
transport_disposed 通信セッションが破棄されました
sandbox_destroyed サンドボックスが破棄されました
sandbox_lifetime_changed サンドボックスのライフタイム設定が変わりました
recovery_exhausted 回復の試行回数を使い切りました
unknown 分類できない中断です

エラー上の便利なゲッターは reason、retryable、operationName です。admitted、operationId、phase、バックアップ関連のメタデータなどは error.context にのみあります（admitted は true | "unknown" です）。

RPCTransportError の kind

kind / context.kind:

Kind 意味
peer_closed ピアが接続を閉じました
connection_failed 接続に失敗しました
upgrade_failed 接続のセットアップに失敗しました
invalid_frame 想定外のフレームです
protocol_error プロトコルがフレームを拒否しました
session_disposed セッションが破棄されました
unknown 分類できない失敗です

Worker とコンテナーイメージの不一致

これらの失敗は、多くの場合、Worker パッケージとコンテナーイメージが一致していない、イメージが起動できない、またはセットアップメタデータが SDK の想定と一致していないことを意味します。デプロイを直してください。遅いコンテナー起動と同じ扱いをしないでください。

Worker パッケージとサンドボックスのコンテナーイメージは、同じ @cloudflare/sandbox@next 系列からデプロイします。プレビューの Worker に安定版イメージを組み合わせる（またはその逆）と、ここで失敗することが多いです。

クラス コード 主要な context 詳細 推奨する対処
RuntimeControlProtocolError INTERNAL_ERROR reason Worker とコンテナーがセットアップを完了できませんでした（メタデータまたはプロトコルの不一致）。コードは共有の INTERNAL_ERROR 値です。このクラスは instanceof RuntimeControlProtocolError、または code === "INTERNAL_ERROR" と context.reason の組み合わせで識別します。 Worker パッケージとコンテナーイメージを同じリリース系列からデプロイします。必要なら設定を直します。

RuntimeControlProtocolError の reason

context.reason:

Reason 意味 備考
unsupported-protocol-version Worker とコンテナーのプロトコルバージョンが一致しません Worker パッケージとコンテナーイメージが同じリリースではありません
missing-metadata コンテナーに必要なセットアップメタデータがありません イメージまたはビルドが不正、または不完全です
malformed-metadata セットアップメタデータを解析できませんでした イメージまたはビルドが不正、または不完全です
activation-mismatch アクティベーションが想定するコンテナーと一致しませんでした コンテナー置き換え後に出ることがあります。繰り返す場合は Worker とイメージの組み合わせを確認します

次の恒久的な問題も関連し、同じ応答を返します。

問題 推奨する対処
wrangler / レジストリのコンテナーイメージが誤り、または不足している Worker パッケージとコンテナーイメージを同じリリース系列からデプロイします。必要なら設定を直します。
準備完了前にコンテナーが終了する イメージまたはエントリポイントを直して再デプロイします。アプリ呼び出しの再試行だけでは不十分です。
アカウントまたはロケーションの容量制限 本番の容量制限 を参照してください

プロセス

クラス コード 主要な context 詳細 推奨する対処
ProcessNotFoundError PROCESS_NOT_FOUND processId 現在のコンテナーに未知のプロセス ID です。 正しい ID を使うか、保存済みの状態からプロセスを再起動します。
StaleProcessHandleError STALE_PROCESS_HANDLE processId、pid、operation 以前のコンテナーのハンドルまたは ID です。 保存済みの状態から作業をやり直します。古いハンドルは再利用しないでください。
ProcessSpawnFailedError PROCESS_SPAWN_FAILED processId、command、cwd?、stderr? プロセスを起動できませんでした。 パス、環境、コマンド、その他の引数を直します。同じ不正なリクエストを再試行しないでください。
InvalidProcessCwdError INVALID_PROCESS_CWD cwd、reason 作業ディレクトリが不正です。 パス、環境、コマンド、その他の引数を直します。同じ不正なリクエストを再試行しないでください。
InvalidProcessEnvironmentError INVALID_PROCESS_ENVIRONMENT name?、reason 環境オーバーレイが不正です。 パス、環境、コマンド、その他の引数を直します。同じ不正なリクエストを再試行しないでください。
InvalidProcessCursorError INVALID_PROCESS_CURSOR processId、cursor?、reason ログカーソルが不正です。 カーソルまたはその他の引数を直します。同じ不正な値を再試行しないでください。
ProcessWaitTimeoutError PROCESS_WAIT_TIMEOUT processId、operation、timeout ローカルの output、waitForExit、または waitForLog がタイムアウトしました。 待機は終了しました。プロセスまたはターミナルはまだ動いている可能性があります。
ProcessAbortedError PROCESS_ABORTED processId、operation ローカルの AbortSignal が待機またはストリームを終了しました。 待機は終了しました。プロセスまたはターミナルはまだ動いている可能性があります。
ProcessReadyTimeoutError PROCESS_READY_TIMEOUT processId、command、condition、timeout 準備完了の待機がタイムアウトしました。 別のプロセスを起動する前に、対象プロセスがまだ動いているかを確認します。
ProcessExitedBeforeReadyError PROCESS_EXITED_BEFORE_READY processId、command、condition、exitCode 準備完了前にプロセスが終了しました。 コマンドまたは環境を直し、必要なら再起動します。
ProcessExitedBeforeLogError PROCESS_EXITED_BEFORE_LOG processId、pid、exit ログ一致の前にプロセスが終了しました。 コマンドまたは環境を直し、必要なら再起動します。
ProcessError PROCESS_ERROR processId、pid?、exitCode?、stderr? 一般的なプロセス失敗です。 状態を変える処理を繰り返す前に、サンドボックスまたはアプリの状態を確認します。

getProcess と listProcesses が null または [] を返すことは、エラーではありません。

ターミナル

クラス コード 主要な context 詳細 推奨する対処
TerminalNotFoundError TERMINAL_NOT_FOUND terminalId 現在のコンテナーに未知のターミナル ID です。 正しい ID を使うか、保存済みの状態からターミナルを再起動します。
StaleTerminalHandleError STALE_TERMINAL_HANDLE terminalId、operation 以前のコンテナーのハンドルまたは ID です。 保存済みの状態から作業をやり直します。古いハンドルは再利用しないでください。
InvalidTerminalCwdError INVALID_TERMINAL_CWD terminalId、cwd、reason 作成時の作業ディレクトリが不正です。 パス、環境、コマンド、その他の引数を直します。同じ不正なリクエストを再試行しないでください。
InvalidTerminalCursorError INVALID_TERMINAL_CURSOR terminalId、cursor?、reason 出力カーソルが不正です。 カーソルまたはその他の引数を直します。同じ不正な値を再試行しないでください。
TerminalControlError TERMINAL_CONTROL_ERROR terminalId、operation、reason? 割り込み、終了、リサイズ、または関連する制御に失敗しました。 状態を変える処理を繰り返す前に、サンドボックスまたはアプリの状態を確認します。

getTerminal と listTerminals が null または [] を返すことは、エラーではありません。

バックアップ

クラス コード 詳細 推奨する対処
BackupCreateError BACKUP_CREATE_FAILED バックアップの作成に失敗しました。 失敗の詳細を確認します。オプションが不正なら直します。
BackupRestoreError BACKUP_RESTORE_FAILED バックアップの復元に失敗しました。 失敗の詳細を確認します。オプションが不正なら直します。
BackupNotFoundError BACKUP_NOT_FOUND 未知のバックアップ ID です。 パス、環境、コマンド、その他の引数を直します。同じ不正なリクエストを再試行しないでください。
BackupExpiredError BACKUP_EXPIRED バックアップの有効期限が切れています。 オプションを直すか、新しいバックアップを作成します。
InvalidBackupConfigError INVALID_BACKUP_CONFIG バックアップオプションが不正です。 パス、環境、コマンド、その他の引数を直します。同じ不正なリクエストを再試行しないでください。

その他のドメイン

これらのクラスは @cloudflare/sandbox/errors から利用できます（一部のマウントヘルパーはパッケージルートからも利用できます）。詳細はインストール済みパッケージで確認してください。すべてのドメイン向けのプレビュー専用ガイドは、まだ公開されていないものがあります。

ドメイン 例 推奨する対処
ファイルシステム FileNotFoundError、FileExistsError、PermissionDeniedError、FileTooLargeError、FileSystemError パスを直すか、存在しないファイルを処理します。
ポート / プレビュー PortAlreadyExposedError、PortNotExposedError、InvalidPortError、PortInUseError、ServiceNotRespondingError、CustomDomainRequiredError ポートオプションまたは公開設定を直します。
インタープリター（拡張） InterpreterNotReadyError、ContextNotFoundError、CodeExecutionError インタープリターの準備ができていない場合は、バックオフして再試行します。それ以外はリクエストを直します。
マウント BucketMountError、BucketUnmountError、S3FSMountError、MissingCredentialsError、InvalidMountConfigError マウントオプションまたは認証情報を直します。
バリデーション ValidationFailedError パス、環境、コマンド、その他の引数を直します。同じ不正なリクエストを再試行しないでください。

インストール済みパッケージの @cloudflare/sandbox/errors には、ほかのドメインクラスがある場合があります。文書化されていない面に依存する前に、そのパッケージで確認してください。

マウント関連のエラーは、マウント API のそばで @cloudflare/sandbox からもエクスポートされます。

プラットフォームヘルパー

ヘルパー 詳細 推奨する対処
isPlatformTransientError(error) 一部の一時的なプラットフォーム信号で true になります（接続喪失、一部の Durable Object ストレージ起動リセット、再試行可能なプラットフォームエラーなど）。 新しいリクエストまたは操作を優先します。
isDurableObjectCodeUpdateReset(error) コード更新またはデプロイで Durable Object の isolate が置き換えられたときに true になります。 同じリクエスト内で再試行し続けないでください。新しい isolate 上で新しいリクエストを実行します。

これらのヘルパーは SandboxError のサブクラスを補完します。エラーと回復 の回復ルールの代わりにはなりません。

本番の容量制限

本番では、アカウントまたはデプロイの制限を超えると、Containers プラットフォームが処理を拒否することがあります（例: SURPASSED_BASE_LIMITS、SURPASSED_TOTAL_LIMITS、LOCATION_SURPASSED_BASE_LIMITS）。同じ過負荷を再試行しても直りません。同時実行を減らす、制限を上げる、またはオペレーター向けの経路に失敗させます。これらの制限は、通常、ローカルの wrangler dev では出ません。

プラットフォームの制限 を参照してください。

関連情報

役に立ちましたか？