← Sandbox SDK / sandbox / 1-0-preview / api

Ошибки

Классы и коды ошибок, возвращаемые Sandbox SDK 1.0 preview, с краткими рекомендуемыми действиями. Полные процедуры восстановления см. в Ошибки и восстановление.

Операции выбрасывают исключения, которые можно перехватить. Предпочтительнее используйте instanceof для классов из @cloudflare/sandbox. Используйте 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, и другие ошибки предметной области (файлы, порты, интерпретатор, точки монтирования и связанные типы контекста):

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";

Большинство ошибок SDK наследуются от SandboxError:

RuntimeIdentityInactiveError расширяет Error напрямую (а не SandboxError). Это означает, что текущий контейнер больше не является активным для этого handle или вызова.

Таблицы включают Рекомендуемое исправление столбце. Подробные процедуры восстановления см. Ошибки и восстановление.

Ошибки доступности и ошибки несоответствия развёртывания описаны в отдельных разделах. Не используйте один и тот же цикл повторов для обоих типов ошибок.

Эти ошибки возникают из-за обычного запуска, остановки при простое, замены или потери связи во время выполнения вызова.

context.reason:

reason / context.reason:

Удобные геттеры у ошибки: reason, retryable, а также operationName. Другие поля, такие как admitted, operationId, phase, и метаданные, связанные с резервным копированием, находятся на error.context только (admitted это true | "unknown").

kind / context.kind:

Такие сбои обычно означают, что пакет Worker и образ контейнера не соответствуют друг другу, образ не может запуститься или метаданные настройки не совпадают с тем, что ожидает SDK. Исправьте развёртывание. Не воспринимайте это как медленный запуск контейнера.

Разверните пакет Worker и образ контейнера песочницы из одной и той же @cloudflare/sandbox@next строка. Именно здесь часто возникает сбой, если preview Worker использует стабильный образ (или наоборот).

context.reason:

Следующие постоянные проблемы связаны между собой и возвращают одинаковый ответ:

getProcess и listProcesses возвращая null или [] не является ошибкой.

getTerminal и listTerminals возвращая null или [] не является ошибкой.

Эти классы доступны из @cloudflare/sandbox/errors (а также некоторых вспомогательных инструментов монтирования из корня пакета). Уточняйте детали по фактически установленному у вас пакету. Руководства по preview пока опубликованы не для всех доменов.

Другие классы доменов могут существовать в @cloudflare/sandbox/errors в установленном у вас пакете. Прежде чем полагаться на недокументированные возможности, сверьтесь с этим пакетом.

Ошибки, связанные с подключением, также экспортируются из @cloudflare/sandbox рядом с API монтирования.

Эти вспомогательные функции дополняют SandboxError подклассы. Они не заменяют правила восстановления для Ошибки и восстановление.

В продакшене платформа Containers может отклонять задачи при превышении лимитов аккаунта или деплоя (например SURPASSED_BASE_LIMITS, SURPASSED_TOTAL_LIMITS, LOCATION_SURPASSED_BASE_LIMITS). Повторный запуск той же перегруженной операции проблему не решит. Снизьте параллелизм, увеличьте лимиты или предусмотрите запасной путь с участием оператора. Обычно эти лимиты не проявляются при локальной wrangler dev.

См. Лимиты платформы.

• Ошибки и восстановление
• Жизненный цикл песочницы
• API процессов
• Terminals API
• Миграция