← Sandbox SDK / sandbox / 1-0-preview

Устранение неполадок

Используйте эту таблицу соответствия симптомов и решений. Для более подробного восстановления см. Ошибки и восстановление. О поведении жизненного цикла см. Жизненный цикл песочницы.

Развёртывание и образ

Симптом	Что проверить
`RuntimeControlProtocolError`, сбои управления или протокола после развёртывания	Пакет Worker и образ контейнера относятся к разным линейкам. Используйте одну и ту же `@next` / `cloudflare/sandbox:next` (или в точности такой же prerelease-версии) пара.
Контейнер так и не становится готовым, или вы видите повторяющиеся `ContainerUnavailableError`	Холодный старт или нехватка мощности. Сделайте паузу перед повторной попыткой, используя `retryAfterMs` если установлено, затем повторите работа. См. Ошибки и восстановление.
Работает в `wrangler dev`, завершается ошибкой только в продакшене	Ограничения только для продакшена и холодный старт. Версии пакета и образа по-прежнему должны совпадать.

Процессы

Симптом	Что проверить
`await exec` «завершился», а команда нет	`exec` разрешается при запуск. Используйте `output()`, `waitForExit()`, или `exitCode`.
Нет stdout в виде строки	`output()` по умолчанию использует байты. Передайте `{ encoding: "utf8" }`.
`getProcess` это `null` / list имеет значение `[]`	Нет запущенного контейнера, или ID неизвестен в текущий контейнер. Обнаружение не пробуждает песочницу. При необходимости перезапустите её из сохранённого состояния задачи.
`StaleProcessHandleError`	Дескриптор был от предыдущего контейнера. Создайте новый `exec` из сохранённой контрольной точки работы.
Время ожидания истекло или ожидание прервано, но процесс всё ещё работает	Только локальное ожидание. Вызовите `kill()` если вы планируете его остановить.
Порт так и не становится готовым	По умолчанию `waitForPort` режим: TCP. Используйте `mode: "http"` для HTTP-проверок. Процесс, возможно, завершился: проверьте статус и логи.
Требуется интерактивный stdin	Не в дескрипторе процесса. Используйте терминал или неинтерактивный argv/`cwd`/`env`.

Терминалы

Симптом	Что проверить
Браузер по-прежнему использует `sessionId`	Вспомогательная функция предпросмотра xterm ожидает `terminalId`.
`getTerminal` это `null`	Те же правила времени жизни, что и у процессов. Создайте заново, если контейнер был заменён.
При повторном подключении история отсутствует	Передайте последние `cursor` в `connect` / параметры вывода.

Окружение и секреты

Симптом	Что проверить
Env из предыдущего `exec` «пропала»	Нет оболочки сессии. Используйте `setEnvVars` и/или для отдельного запуска `env`. Переменные окружения.
Утечка API-ключей в контейнер	Не размещайте боевые секреты в sandbox env. Используйте исходящий трафик обработчики на Worker.

Interpreter

Симптом	Что проверить
`sandbox.createCodeContext is not a function`	Подключите `withInterpreter` и вызвать `sandbox.interpreter.*`.
Python недоступен	Используйте `-python` вариант образа на той же `@next` строка.

Bridge HTTP

Симптом	Что проверить
Bridge `/exec`, сессии или `/pty` поведение отличается от `@next` документация по Worker SDK	Самостоятельно развёрнутый мост не входит в превью 1.0. Используйте стабильный мост с совпадающими версиями стабильного пакета и образа контейнера.

Агенты и долгоживущие задачи

Для агентов и долго выполняющихся инструментов на @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, и другие).