← Sandbox SDK / sandbox / 1-0-preview

Chyby a zotavení

Některá selhání znamenají, že kontejner vaši práci vůbec nespustil. Jiná znamenají, že práce už mohla začít. Tyto případy vyžadují odlišné zotavení.

Stejné ID sandboxu může později použít nový kontejner. Procesy, terminály a lokální soubory z předchozího containeru se samy neobnoví. Viz Životní cyklus sandboxu a Jak dlouho proces žije.

Katalog tříd: API chyb. Tabulka příznaků: Řešení potíží.

Pokud kontejner není připravený, SDK může vyvolat ContainerUnavailableError (CONTAINER_UNAVAILABLE). Operace neproběhla uvnitř kontejneru.

K tomu často dochází při studeném startu, po zastavení kvůli nečinnosti nebo během nasazení.

Kontext chyby zahrnuje retryable: true, reason (například container_starting), a volitelné retryAfterMs. Zpomalte (použijte retryAfterMs je-li přítomna), a poté zkuste stejný typ práce znovu.

Stejné pravidlo „vždy opakovat“ nepoužívejte pro chyby, které nastanou až poté, co kontejner již mohl začít pracovat.

import { ContainerUnavailableError } from "@cloudflare/sandbox";

try {
	const process = await sandbox.exec(["npm", "install"], {
		cwd: "/workspace/app",
	});
	await process.waitForExit();
} catch (error) {
	if (error instanceof ContainerUnavailableError) {
		// Safe to retry the whole operation after backoff.
	}
}

import { ContainerUnavailableError } from "@cloudflare/sandbox";

try {
	const process = await sandbox.exec(["npm", "install"], {
		cwd: "/workspace/app",
	});
	await process.waitForExit();
} catch (error) {
	if (error instanceof ContainerUnavailableError) {
		// Safe to retry the whole operation after backoff.
	}
}

Jakmile kontejner přijme operaci, selhání může zanechat částečné výsledky: proces může běžet, soubor může existovat, záloha mohla začít.

OperationInterruptedError znamená, že se kontejner nebo sandbox změnil, zatímco volání již probíhalo. Práce mohla být zahájena.

Použijte reason a retryable u chyby (přečtěte si API chyb u polí). Pokud kroky mění stav, zkontrolujte sandbox nebo své vlastní záznamy, než stejné kroky spustíte znovu.

RPCTransportError znamená, že SDK ztratilo kontakt s aktuálním kontejnerem během volání. Pozdější volání může proti stejnému kontejneru znovu uspět.

To provede ne znamenají, že přerušené volání nic neprovedlo. Před opakováním stejné práce dávejte přednost kontrolním bodům a krokům, které lze bezpečně spustit dvakrát, nebo zkontrolujte stav. Diagnostické kind hodnoty jsou uvedeny na API chyb.

ID procesů a terminálů patří do aktuální kontejner pro dané sandbox ID. Po zastavení nebo nahrazení volání na starém handlu vyvolají StaleProcessHandleError nebo StaleTerminalHandleError. getProcess, getTerminal, listProcesses, a listTerminals nespouštějí kontejner. Vrací null nebo [] když neběží žádný kontejner nebo když je ID v aktuálním kontejneru neznámé. Nejde o výjimku.

Uložte úlohu (příkaz, cwd, env, checkpoint), nejen ID prostředku. Poté spusťte nový exec nebo createTerminal když starý handle již neexistuje.

Časové limity a AbortSignal na output(), waitForExit(), waitForLog(), waitForPort(), a logs() konec které pouze čekají nebo streamují. Proces tím neukončí. Zrušení výstupu terminálu neukončuje PTY.

Použijte process.kill() nebo terminal.interrupt() / terminal.terminate() když daný prostředek hodláte zastavit. Typické chyby: ProcessWaitTimeoutError, ProcessAbortedError.

Neplatný cwd nebo proměnné prostředí, chybějící spustitelný soubor nebo podobné problémy s požadavkem selhávají, dokud tyto hodnoty nezměníte. Stejný neplatný požadavek neopakujte. Typické kategorie: InvalidProcessCwdError, InvalidProcessEnvironmentError, ProcessSpawnFailedError.

Některá selhání znamenají, že si balíček Workeru a image kontejneru neodpovídají, že se image nepodařilo spustit nebo že selhalo nastavení mezi Workerem a kontejnerem.

Detail katalogu: Neshoda mezi Workerem a image kontejneru.

Nejedná se o totéž jako pomalý start (ContainerUnavailableError). Pro obojí nepoužívejte stejnou smyčku opakování s odkladem.

Chyba: ContainerUnavailableError

Počkejte s opakováním a poté spusťte celou jednotku práce znovu (například nastavení plus exec), ne libovolný mezikrok bez checkpointu.

1. Uložte úlohu a kontrolní bod (a ID procesu nebo terminálu, dokud je to užitečné).
2. Při pozdějším požadavku zavolejte getProcess nebo getTerminal pokud stále máte ID.
3. Pokud získáte handle, pokračujte (logy, připojení, čekání).
4. Pokud se zobrazí null nebo chybu zastaralého handle, začněte znovu od kontrolního bodu.
5. Pokud se zobrazí ContainerUnavailableError, počkejte a pokračujte novou operací.

Chyba: OperationInterruptedError

Přečtěte si reason a retryable. Pokud mohlo volání něco změnit, před jeho opakováním to ověřte.

Chyba: RPCTransportError

Zaznamenejte kind pokud potřebujete diagnostiku. Předpokládejte, že rozpracovaná práce mohla proběhnout. Pokračujte od checkpointů nebo na základě kontroly stavu a poté spusťte novou operaci, pokud ji úloha ještě potřebuje.

Chyby: ProcessWaitTimeoutError, ProcessAbortedError

Buď dále sledujte (getProcess a logs({ since })) nebo proces zastavte pomocí kill. Nepředpokládejte, že proces skončil jen proto, že čekání skončilo.

Chyby: InvalidProcessCwdError, InvalidProcessEnvironmentError, ProcessSpawnFailedError, a podobné

Opravte cestu, prostředí nebo příkaz (případně soubory v image, pokud binárka chybí). Neopakujte akci s nezměněnými hodnotami.

Situace: Po nasazení volání selhávají s chybami protokolu nebo nastavení, případně kontejner nikdy nezačne fungovat.

Chyby / signály: RuntimeControlProtocolError; nesprávný image; kontejner skončí dříve, než je připraven

Dělejte: Znovu nasaďte balíček Workeru a image kontejneru ze stejného @cloudflare/sandbox@next řádek. Zkontrolujte název obrazu a vstupní bod.

Nedělejte: Přistupujte k tomu jako k pomalému startu kontejneru a jen počkejte, než to zkusíte znovu.

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

try {
	const process = await sandbox.exec(["npm", "test"], {
		cwd: "/workspace/app",
	});
	const result = await process.output({ encoding: "utf8" });
	console.log(result.exitCode, result.stdout);
} catch (error) {
	if (error instanceof ContainerUnavailableError) {
		// Container never started the work — back off, then try the work again.
	} else if (error instanceof StaleProcessHandleError) {
		// Previous container — start again from what you stored about the work.
	} else if (error instanceof OperationInterruptedError) {
		// Work may have started — read reason/retryable and check state before repeating.
	} else if (error instanceof RPCTransportError) {
		// Lost contact during the call — a later call may work; this call may already have run.
	} else if (
		error instanceof ProcessWaitTimeoutError ||
		error instanceof ProcessAbortedError
	) {
		// Wait ended only — process may still be running.
	} else {
		throw error;
	}
}

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

try {
	const process = await sandbox.exec(["npm", "test"], {
		cwd: "/workspace/app",
	});
	const result = await process.output({ encoding: "utf8" });
	console.log(result.exitCode, result.stdout);
} catch (error) {
	if (error instanceof ContainerUnavailableError) {
		// Container never started the work — back off, then try the work again.
	} else if (error instanceof StaleProcessHandleError) {
		// Previous container — start again from what you stored about the work.
	} else if (error instanceof OperationInterruptedError) {
		// Work may have started — read reason/retryable and check state before repeating.
	} else if (error instanceof RPCTransportError) {
		// Lost contact during the call — a later call may work; this call may already have run.
	} else if (
		error instanceof ProcessWaitTimeoutError ||
		error instanceof ProcessAbortedError
	) {
		// Wait ended only — process may still be running.
	} else {
		throw error;
	}
}

Upřednostněte instanceof s třídami z @cloudflare/sandbox. Úplné tabulky: API chyb.

• Životní cyklus sandboxu
• API chyb
• Provádění procesů
• Terminály
• Migrace
• Processes API · Terminals API