> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recover from a known-good image

> Diagnose a deliberate command failure and retry corrected work from the recorded checkpoint.

Recovery begins from an immutable checkpoint whose contents were already verified. This avoids assuming that a failed, cancelled, or timed-out operation produced reusable state.

## Prerequisites and complete source

Complete [Set up access](/sandboxes/start/set-up-access). In a fresh project, run `uv init --python 3.12` and `uv add "contree-sdk==0.3.6"`. Save as `recover.py`:

```python theme={null}
import asyncio
from contree_sdk import Contree


async def main() -> None:
    client = Contree()
    base = await client.images.oci("docker.io/library/alpine:3.19")
    checkpoint = await base.run(
        shell="mkdir -p /work && printf 'known-good\\n' > /work/state.txt",
        disposable=False, timeout=30,
    )
    if checkpoint.exit_code != 0 or checkpoint.uuid is None:
        raise RuntimeError('Preparation failed or returned no saved checkpoint')
    known_good_uuid = checkpoint.uuid
    print(f"Saved known-good checkpoint: {known_good_uuid}")

    known_good = await client.images.use(known_good_uuid, strict=True)
    failed = await known_good.run(
        shell="test \"$(cat /work/state.txt)\" = wrong-value",
        disposable=True, timeout=30,
    )
    if failed.exit_code == 0:
        raise RuntimeError('The intentionally wrong check unexpectedly passed')
    print(f"deliberate failure exit={failed.exit_code} stderr={failed.stderr!r}")

    retry_base = await client.images.use(known_good_uuid, strict=True)
    recovered = await retry_base.run(
        shell="test \"$(cat /work/state.txt)\" = known-good && printf 'recovered\\n'",
        disposable=True, timeout=30,
    )
    if recovered.exit_code != 0 or recovered.stdout != "recovered\n":
        raise RuntimeError('Retry did not produce the expected recovered output')
    print(f"checkpoint={known_good_uuid} recovered")


asyncio.run(main())
```

Run `uv run python recover.py`. You should see the intentional command failure, followed by `recovered` from the same known-good image.

Both attempts are disposable because they only check the saved file and print a result. Record stdout, stderr, exit code, truncation, and the operation ID when using REST. A nonzero exit is a workload result; an SDK exception can represent a platform failure, cancellation, or wait timeout. SDK 0.3.6 makes a best-effort cancellation when its wait times out. After uncertain transport or cancellation, inspect the existing operation before retrying. For files from a failed run, follow the [result-image rules](/sandboxes/concepts/images-checkpoints-and-branches#interpret-the-result-image).

See [Troubleshooting](/sandboxes/operate/troubleshooting).