> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Troubleshooting: Volumes

Last updated 17 November 2026

Look first at the refusal’s code: the answer names it in `code`, and the CLI prints it. A Volume that does something you did not expect, with no refusal, is under [While it is in use](#in-use). Every refusal of a Machine is on [Troubleshooting](https://tonbo.dev/docs/machines/troubleshooting.md).

## Creating a Volume {#create}

| Answer | Why | What to do |
| --- | --- | --- |
| `402 payment_required` | Your credit is used up, so nothing new is created. Or your account has never bought credit: making a port public then needs a card on the account (`errors` names `ports`), and it holds one Volume, in any region, of at most 10 GiB, or 100 GiB once it has a card (a larger size names `size_gib`). | On Usage & billing, add a card for a public port or for a Volume of up to 100 GiB (adding one charges nothing), or buy credit, which opens ports and lifts both Volume limits; the answer’s detail links your account’s page. Then send the request again (see [Credit](https://tonbo.dev/docs/machines/pricing.md#credit)). |
| `422 region_not_offered` | Machines do not run in the region named, or in your account’s default region. | Name a region where they run with `--region` (see [Regions](https://tonbo.dev/docs/machines/manage.md#regions)). |

| Answer | Why | What to do |
| --- | --- | --- |
| `409 conflict` to a Volume create | Another Volume of your account, in any region, has that name, or your account already holds 25 Volumes. | `tonbo volume list` (`GET /v1/volumes`) shows them; choose another name, or delete a Volume you no longer need. |

## Binding or moving a Volume {#bind}

These answer a Machine create or update that names a Volume, or `tonbo volume move`; each is also a row of [Troubleshooting: managing Machines](https://tonbo.dev/docs/machines/troubleshooting/manage.md). Nothing is written when one answers.

| Answer | Why | What to do |
| --- | --- | --- |
| `422 volumes_not_offered` | The request set the volumes field, and Volumes are not offered in the Machine’s region yet. | Leave volumes out until they are offered there, and keep data in a database the Machine binds. |
| `422 root_mode_not_offered` | The request bound a Volume with no path, which makes it the Machine’s whole disk, and the Machine’s region does not offer that. | Give the Volume a path to mount it there, such as data:/data, or leave the Volume out. |
| `409 volume_attached` | The request moved a Volume (move_from) from a Machine that is awake with it attached, or onto a Machine that is awake with its own Volume attached. The answer’s machine names which. | `tonbo machine sleep <machine>` (`POST /v1/machines/<machine>/sleep`), then move it again. |
| `409 volume_holder_changed` | The request moved a Volume from the Machine named in move_from, but another Machine holds it now (the answer’s holder), or none does. A Volume is only taken from the Machine you name. | `tonbo volume show <volume>` (`GET /v1/volumes/<volume>`) shows its Machine; name that one in move_from. |
| `409 volume_image_mismatch` | The Volume is a Machine’s whole disk, made against one image digest (volume_digest), and the Machine it was moving to runs another (machine_digest). | Move it to a Machine on the same image, or create one with that image. |
| `409 volume_mode_change` | The request gave the Machine’s whole disk a path, or moved a Volume between being a whole disk and being mounted at a path. A whole disk is never mounted at a path; a Volume mounted at a path becomes a whole disk only on its own Machine, or unbound, with its files under /workspace. | Send the binding as it is now, or bind a new Volume in the mode you want. |
| `409 volume_rebuild_pending` | The Volume is a whole disk with a Rebuild that its Machine applies at its next wake. | `tonbo machine wake <machine>` (`POST /v1/machines/<machine>/wake`) once, then move it. |

| Answer | Why | What to do |
| --- | --- | --- |
| `409 conflict` to a Machine create or update that names a Volume | Another Machine has the Volume, or the Volume is in another region than the Machine. | To take it from the Machine that has it, move it (see [Move a Volume](https://tonbo.dev/docs/machines/manage.md#move-a-volume)); otherwise name a Volume of the Machine’s region. |

## Deleting a Volume {#delete}

| Answer | Why | What to do |
| --- | --- | --- |
| `409 conflict` to a Volume delete | A Machine has the Volume, and a Volume is deleted only once no Machine has it. | `tonbo machine update <machine> --no-volume` (`PATCH /v1/machines/{name}` with `{"volumes": []}`); if the Machine is awake, `tonbo machine sleep <machine>` too. Then delete the Volume again. |

When a Volume is deleted with its Machine, and when it is kept, is on [Deleting its Machine](https://tonbo.dev/docs/machines/volumes/things-to-know.md#delete-machine).

## While it is in use {#in-use}

| What you see | Why | What to do |
| --- | --- | --- |
| Reads are slow just after a wake, then speed up. | The Machine woke on another server than the one holding its Volume’s working copy, so blocks are fetched from the region’s storage the first time they are read. | Expected; reads reach local speed as the copy fills in (see [A wake on the same server, or on another](https://tonbo.dev/docs/machines/volumes/how-it-works.md#wakes)). |
| `fsync` or writes take a long time, or `tonbo volume show --json` gives a `writes_held` that is not null. | fsync waits while copying the Volume to the region’s storage is five minutes behind, until it catches up. A writes_held that is not null says since when the Volume has held its Machine’s writes, and why; a held write is answered once a copy catches up, and never failed. | Wait; it ends by itself when the copy catches up. If it does not, Tonbo stops the Machine (see [the next row](#volume-stopped)). |
| A Machine with a Volume stopped while it was awake, its wake history (`tonbo machine activations <machine>`) ending that wake with `platform_release`; or one of its wakes failed. | Tonbo could not serve the Volume on that server: the software serving it stopped, copying could not catch up, or the Volume had already been restored on another server after this one stopped responding. | Send the request again; the next wake gets the Volume as it was last kept. If it was restored on another server, what was written since its last finished copy is gone (see [When a server is lost or stops responding](https://tonbo.dev/docs/machines/volumes/how-it-works.md#server-loss)). |
| Requests to the Machine are refused with [`capacity`](https://tonbo.dev/docs/machines/troubleshooting/call.md#capacity) for up to 10 minutes. | The server that holds the Volume’s working copy stopped responding while the Machine was awake, and its disk may hold writes no copy has, so Tonbo waits up to 10 minutes for it before restoring the Volume elsewhere. | Send the request again after Retry-After; the Machine wakes once the server answers, or on another server once the wait ends. |
| Files written shortly before are missing, or older, after a wake. | The server was lost while the Machine was awake, and the Volume came back from its last finished copy; or the files were written with no fsync before a crash. | Call `fsync` after writes that matter, and keep what must be safe off the server at once in a database (see [Keep data on a Volume or in a database](https://tonbo.dev/docs/machines/database.md)). What a write survives is on [Data guarantees](https://tonbo.dev/docs/machines/guarantees/data/volume.md). |
| `tonbo machine show --json` lists a `volume_purged` condition, and the Machine boots without its Volume. | The Volume the Machine names was deleted, with its data: it was deleted on its own, its account was deleted, or the account went unpaid long after its owners were told. | Bind another Volume to the Machine, or none; that clears the condition. The data cannot be recovered. |
| A wake is refused, and `status.conditions` has `wake_blocked` with the reason `root_image_mismatch`. | The Machine’s Volume is its whole disk, made over another image than the Machine now has. | Rebuild the Machine on its image (see [Change the image with a Rebuild](https://tonbo.dev/docs/machines/whole-disk.md#rebuild)). |
| Moving a file onto the Volume over HTTPS answers `409 cross_device`. | A move is one atomic step, and it cannot cross from the Machine’s own disk to its Volume. | Copy it with a command instead (see [Read and write files](https://tonbo.dev/docs/machines/files.md)). |
